Admin API

The Admin API provides endpoints for programmatically managing which engineers are onboarded and offboarded in Bilanc. This is useful for automating user lifecycle management — for example, syncing your Active Directory or GitHub organisation membership with Bilanc. Users can be identified by their email address or GitHub username.

These endpoints require an Organisation API Key. To generate one, click your name in the bottom-left corner of the Bilanc app, select Account Settings, then navigate to Organisation API Keys. If you don’t see this page, contact an owner in your organisation.

Base URL

https://api.bilanc.co

Authentication

All Admin API requests require an API key in the Authorization header:

Authorization: YOUR_API_KEY

List Onboarded Users

Retrieve all currently onboarded users in your organisation, including their name, email, and GitHub username.

GET /users/onboarded-users-by-attributes

Parameters

This endpoint does not require any request body or query parameters.

Example

curl -X GET 'https://api.bilanc.co/users/onboarded-users-by-attributes' \
  -H 'Authorization: YOUR_API_KEY'

import requests

API_KEY = "YOUR_API_KEY"

response = requests.get(
    "https://api.bilanc.co/users/onboarded-users-by-attributes",
    headers={"Authorization": f"{API_KEY}"},
)

data = response.json()
print(data)

const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';

const response = await axios.get(
  'https://api.bilanc.co/users/onboarded-users-by-attributes',
  {
    headers: {
      'Authorization': `${API_KEY}`,
    },
  }
);

console.log(response.data);

Response

{
  "users": [
    {
      "merged_user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Jane Smith",
      "email": "jane.smith@company.co.uk",
      "github_username": "janesmith-company"
    },
    {
      "merged_user_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "John Doe",
      "email": "john.doe@company.co.uk",
      "github_username": "johndoe"
    }
  ],
  "total_users_found": 2
}

Response Fields

array

List of onboarded users, each containing:

merged_user_id — Unique identifier for the user in Bilanc
name — The user’s display name
email — The user’s primary email address
github_username — The user’s GitHub login

integer

Total number of onboarded users returned.

Onboard Users

Onboard one or more users by providing their email addresses and/or GitHub usernames. Bilanc will match these against existing users in your data sources and add them as onboarded engineers.

POST /users/onboarded-users-by-attributes

Request Body

string[]

List of email addresses to onboard. At least one of email_addresses or github_usernames must be provided.

string[]

List of GitHub usernames to onboard. At least one of email_addresses or github_usernames must be provided.

You can provide both email_addresses and github_usernames in the same request. Bilanc will match users against either identifier.

Example

curl -X POST 'https://api.bilanc.co/users/onboarded-users-by-attributes' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email_addresses": [
      "jane.smith@company.co.uk",
      "john.doe@company.co.uk"
    ],
    "github_usernames": [
      "janesmith-company"
    ]
  }'

import requests

API_KEY = "YOUR_API_KEY"

response = requests.post(
    "https://api.bilanc.co/users/onboarded-users-by-attributes",
    headers={
        "Authorization": f"{API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "email_addresses": [
            "jane.smith@company.co.uk",
            "john.doe@company.co.uk",
        ],
        "github_usernames": [
            "janesmith-company",
        ],
    },
)

data = response.json()
print(data)

const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';

const response = await axios.post(
  'https://api.bilanc.co/users/onboarded-users-by-attributes',
  {
    email_addresses: [
      'jane.smith@company.co.uk',
      'john.doe@company.co.uk',
    ],
    github_usernames: [
      'janesmith-company',
    ],
  },
  {
    headers: {
      'Authorization': `${API_KEY}`,
      'Content-Type': 'application/json',
    },
  }
);

console.log(response.data);

Response

{
  "message": "Users were successfully onboarded",
  "onboarded_count": 2,
  "onboarded_user_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ],
  "total_users_found": 2,
  "not_found": {
    "email_addresses": [],
    "github_usernames": []
  },
  "warnings": []
}

Response Fields

string

A summary of the result, e.g. "Users were successfully onboarded" or "All users are already onboarded".

integer

Number of users that were newly onboarded.

string[]

List of Bilanc user IDs that were onboarded.

integer

Total number of users matched from the provided identifiers.

object

Contains any identifiers that could not be matched to existing users:

email_addresses — Unmatched email addresses
github_usernames — Unmatched GitHub usernames

string[]

List of warnings, e.g. ["Some users were not found"] if any identifiers could not be matched.

Partial Matches

If some identifiers are found and others are not, the endpoint will onboard the matched users and return the unmatched identifiers in the not_found field. Check warnings to see if any identifiers were not found.

Offboard Users

Offboard one or more users by providing their email addresses and/or GitHub usernames. This removes the users from your onboarded engineers list.

POST /users/offboarded-users-by-attributes

Request Body

string[]

List of email addresses to offboard. At least one of email_addresses or github_usernames must be provided.

string[]

List of GitHub usernames to offboard. At least one of email_addresses or github_usernames must be provided.

Example

curl -X POST 'https://api.bilanc.co/users/offboarded-users-by-attributes' \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email_addresses": [
      "leaver@company.co.uk"
    ],
    "github_usernames": [
      "former-employee"
    ]
  }'

import requests

API_KEY = "YOUR_API_KEY"

response = requests.post(
    "https://api.bilanc.co/users/offboarded-users-by-attributes",
    headers={
        "Authorization": f"{API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "email_addresses": [
            "leaver@company.co.uk",
        ],
        "github_usernames": [
            "former-employee",
        ],
    },
)

data = response.json()
print(data)

const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';

const response = await axios.post(
  'https://api.bilanc.co/users/offboarded-users-by-attributes',
  {
    email_addresses: [
      'leaver@company.co.uk',
    ],
    github_usernames: [
      'former-employee',
    ],
  },
  {
    headers: {
      'Authorization': `${API_KEY}`,
      'Content-Type': 'application/json',
    },
  }
);

console.log(response.data);

Response

{
  "message": "Users were successfully offboarded",
  "offboarded_count": 2,
  "offboarded_user_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ],
  "not_found": {
    "email_addresses": [],
    "github_usernames": []
  },
  "warnings": []
}

Response Fields

string

A summary of the result, e.g. "Users were successfully offboarded".

integer

Number of users that were offboarded.

string[]

List of Bilanc user IDs that were offboarded.

object

Contains any identifiers that could not be matched to onboarded users:

email_addresses — Unmatched email addresses
github_usernames — Unmatched GitHub usernames

string[]

List of warnings if any identifiers could not be matched.

Error Responses

All Admin API endpoints return standard HTTP error codes:

Status Code	Description
`400`	Bad request — at least one of `email_addresses` or `github_usernames` must be provided
`401`	Unauthorised — invalid or missing API key
`404`	No users found matching the provided identifiers
`500`	Internal server error

Example Error Response

{
  "detail": "No users found matching the provided attributes (email addresses: unknown@company.co.uk). Please verify the values and try again."
}

Common Use Cases

Sync with Active Directory: Automate onboarding and offboarding by comparing your AD/SAML user list with Bilanc’s onboarded users
New starter automation: Trigger onboarding via CI/CD or a script when new engineers join your GitHub organisation
Leaver removal: Automatically offboard users when they leave the organisation
Slack workflow integration: Build a Slack workflow that triggers onboarding/offboarding via these endpoints

Admin API

Teams API

Metric Endpoints

Additional Information

Admin API

Admin API

Base URL

Authentication

List Onboarded Users

Parameters

Example

Response

Response Fields

Onboard Users

Request Body

Example

Response

Response Fields

Partial Matches

Offboard Users

Request Body

Example

Response

Response Fields

Error Responses

Example Error Response

Common Use Cases

​Admin API

​Base URL

​Authentication

​List Onboarded Users

​Parameters

​Example

​Response

​Response Fields

​Onboard Users

​Request Body

​Example

​Response

​Response Fields

​Partial Matches

​Offboard Users

​Request Body

​Example

​Response

​Response Fields

​Error Responses

​Example Error Response

​Common Use Cases

Admin API

Base URL

Authentication

List Onboarded Users

Parameters

Example

Response

Response Fields

Onboard Users

Request Body

Example

Response

Response Fields

Partial Matches

Offboard Users

Request Body

Example

Response

Response Fields

Error Responses

Example Error Response

Common Use Cases