> ## Documentation Index
> Fetch the complete documentation index at: https://bilanc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Teams API

> API endpoints for retrieving your organisation’s teams and their members

## Teams API

The Teams API lets you programmatically retrieve the teams in your Bilanc organisation along with their members. This is useful for syncing your org structure into other systems, reporting on team composition, or feeding team data into your own dashboards and automations.

<Warning>
  This endpoint requires 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.
</Warning>

<Note>
  Only the `GET /teams` endpoint is available via API key. Creating, updating, and deleting teams remains available exclusively through the Bilanc dashboard.
</Note>

## Base URL

```
https://api.bilanc.co
```

## Authentication

All Teams API requests require an API key in the `Authorization` header:

```bash theme={null}
Authorization: YOUR_API_KEY
```

***

## List Teams

Retrieve all teams in your organisation, including each team's name, department, and the onboarded members assigned to it.

```
GET /teams
```

### Parameters

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

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://api.bilanc.co/teams' \
    -H 'Authorization: YOUR_API_KEY'
  ```

  ```python Python theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"

  response = requests.get(
      "https://api.bilanc.co/teams",
      headers={"Authorization": f"{API_KEY}"},
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const API_KEY = 'YOUR_API_KEY';

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

  console.log(response.data);
  ```
</CodeGroup>

### Response

```json theme={null}
[
  {
    "team_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "team_name": "Platform",
    "department": "Engineering",
    "members": [
      {
        "merged_user_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "name": "Jane Smith"
      },
      {
        "merged_user_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "name": "John Doe"
      }
    ]
  },
  {
    "team_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "team_name": "Growth",
    "department": null,
    "members": null
  }
]
```

### Response Fields

The endpoint returns an array of team objects, each containing:

<ResponseField name="team_id" type="string">
  Unique identifier for the team in Bilanc.
</ResponseField>

<ResponseField name="team_name" type="string">
  The team's display name.
</ResponseField>

<ResponseField name="department" type="string">
  The department the team belongs to. May be `null` if no department has been set.
</ResponseField>

<ResponseField name="members" type="array">
  List of onboarded users assigned to the team, each containing:

  * `merged_user_id` — Unique identifier for the user in Bilanc
  * `name` — The user's display name

  Will be `null` for teams that have no onboarded members. Only onboarded users are included.
</ResponseField>

<Tip>
  Use the `merged_user_id` values to join team membership with data from other Bilanc endpoints, such as the metric endpoints, which accept `merged_user_id` for filtering and grouping.
</Tip>

***

## Error Responses

The Teams API returns standard HTTP error codes:

| Status Code | Description                               |
| ----------- | ----------------------------------------- |
| `401`       | Unauthorised — invalid or missing API key |
| `500`       | Internal server error                     |

### Example Error Response

```json theme={null}
{
  "detail": "Unexpected error occurred: ..."
}
```

***

## Common Use Cases

* **Sync org structure**: Mirror your Bilanc team and membership data into an internal data warehouse or HR system
* **Team-level reporting**: Combine the `members` list with the metric endpoints to build per-team performance reports
* **Automations**: Drive Slack workflows or scheduled jobs that need an up-to-date view of which engineers belong to which teams