Admin API

API endpoints for managing user onboarding and offboarding

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

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

Response

{
  "users": [
    {
      "merged_user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Jane Smith",
      "email": "[e-mail]",
      "github_username": "janesmith-company"
    },
    {
      "merged_user_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "John Doe",
      "email": "[e-mail]",
      "github_username": "johndoe"
    }
  ],
  "total_users_found": 2
}

Response Fields

users · 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

total_users_found · 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

email_addresses · string[]

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

github_usernames · 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

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": [
      "[e-mail]",
      "[e-mail]"
    ],
    "github_usernames": [
      "janesmith-company"
    ]
  }'

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

message · string

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

onboarded_count · integer

Number of users that were newly onboarded.

onboarded_user_ids · string[]

List of Bilanc user IDs that were onboarded.

total_users_found · integer

Total number of users matched from the provided identifiers.

not_found · object

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

• email_addresses — Unmatched email addresses
• github_usernames — Unmatched GitHub usernames

warnings · 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

email_addresses · string[]

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

github_usernames · string[]

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

Example

cURL

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

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

message · string

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

offboarded_count · integer

Number of users that were offboarded.

offboarded_user_ids · string[]

List of Bilanc user IDs that were offboarded.

not_found · object

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

• email_addresses — Unmatched email addresses
• github_usernames — Unmatched GitHub usernames

warnings · 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: [e-mail]). 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