API reference - TeamBuilder API

Base URL

https://api.teambuilder.ge

Every path starts with /v1. All traffic is HTTPS.

Authentication

Send your key as a Bearer token on every request:

Authorization: Bearer tb_live_...

Each endpoint page lists the scope it needs. See Authentication.

Conventions

Topic	Convention
Format	JSON request and response bodies, `snake_case` keys, UTF-8
Timestamps	ISO 8601 in UTC, for example `2026-10-20T09:30:00.000Z`
Identifiers	TeamBuilder ids are UUIDs. `external_id` fields hold your HR system’s keys.
Lists	`{"data": [...], "pagination": {"next_cursor": ...}}`. See Pagination.
Errors	`{"error": {"code", "message", "request_id"}}`. See Errors.
Rate limits	60 requests per minute per key, reported in `X-RateLimit-*` headers. See Rate limits.
Tracing	Every response carries an `X-Request-Id` header. Quote it when you contact support.
Nullable fields	Documented fields are always present; a field without a value is `null`, never omitted.

Endpoints

Method	Path	Scope
`GET`	`/v1/ping`	any key
`GET`	`/v1/employees`	`employees:read`
`GET`	`/v1/employees/{id}`	`employees:read`
`GET`	`/v1/employees/{id}/stats`	`employees:read`
`GET`	`/v1/employees/{id}/badges`	`employees:read`
`PUT`	`/v1/employees/sync`	`employees:write`
`GET`	`/v1/leaderboard`	`leaderboard:read`
`GET`	`/v1/leaderboard/by-department`	`leaderboard:read`
`GET`	`/v1/departments`	`departments:read`
`GET`	`/v1/shop/items`	`shop:read`

Using the playground

Each endpoint page has a Try it playground. Paste a key into the authorisation field and send real requests.

Playground requests are relayed through Mintlify’s servers, which host this documentation, so the key you paste leaves your machine. Use a tb_test_ key in the playground, never a live key.