# TeamBuilder API

> Developer documentation for the TeamBuilder API: read XP leaderboards, employee stats, badges, departments and the shop catalogue, and sync your employee roster from your HR system.

- [Introduction](https://developers.teambuilder.ge/index.md): Bring TeamBuilder levels, XP leaderboards and rewards into your intranet, and keep your employee roster in sync from your HR system.
- [Quickstart](https://developers.teambuilder.ge/quickstart.md): Make your first request in five minutes: verify a key, read a leaderboard and render it.
- [Authentication](https://developers.teambuilder.ge/authentication.md): API keys, live and test modes, scopes, rotation and how to store keys safely.
- [Leaderboards](https://developers.teambuilder.ge/guides/leaderboards.md): Rank employees by XP for a period, company-wide or within a department, and show every department's leaders at once.
- [Employee widgets](https://developers.teambuilder.ge/guides/employee-widgets.md): Show an employee's level, XP progress, coins, ranks and badges on intranet profiles and dashboards.
- [Shop catalogue](https://developers.teambuilder.ge/guides/shop-catalogue.md): Show the rewards your employees can redeem with their coins, with your company's prices and live stock.
- [Roster sync](https://developers.teambuilder.ge/guides/roster-sync.md): Keep TeamBuilder's employees, departments and job titles in step with your HR system, and deactivate leavers safely.
- [Sandbox and testing](https://developers.teambuilder.ge/guides/sandbox.md): Build against realistic sample data with a tb_test_ key, then switch to live by changing one secret.
- [Pagination](https://developers.teambuilder.ge/reference/pagination.md): Every list endpoint uses the same opaque-cursor envelope.
- [Rate limits](https://developers.teambuilder.ge/reference/rate-limits.md): Per-key request limits, the headers that report them, and how to back off.
- [Errors](https://developers.teambuilder.ge/reference/errors.md): One error shape for every failure, stable machine-readable codes, and a request ID for support.
- [Versioning and support](https://developers.teambuilder.ge/reference/versioning.md): How the API evolves, what counts as a breaking change, and how to reach the team.
- [Changelog](https://developers.teambuilder.ge/changelog.md): New endpoints, additive changes and deprecations in the TeamBuilder API.
- [API reference](https://developers.teambuilder.ge/api-reference/introduction.md): Every TeamBuilder API endpoint, generated from the OpenAPI specification, with a live playground.
- [Check your API key](https://developers.teambuilder.ge/api-reference/status/check-your-api-key.md): Check that a key works and see the company, scopes and mode it carries. Works with any valid key.
- [List employees](https://developers.teambuilder.ge/api-reference/employees/list-employees.md): List active employees, oldest first, or find one by email, external ID or department.
- [Retrieve an employee](https://developers.teambuilder.ge/api-reference/employees/retrieve-an-employee.md): Read one active employee by employee_id.
- [Retrieve employee stats](https://developers.teambuilder.ge/api-reference/employees/retrieve-employee-stats.md): Level, XP, XP to the next level, coin balance, company and department rank, and badge count.
- [List employee badges](https://developers.teambuilder.ge/api-reference/employees/list-employee-badges.md): The badges an employee holds, newest award first.
- [Get the leaderboard](https://developers.teambuilder.ge/api-reference/leaderboard/get-the-leaderboard.md): Employees ranked by XP for a period, company-wide or within one department.
- [Get the leaderboard by department](https://developers.teambuilder.ge/api-reference/leaderboard/get-the-leaderboard-by-department.md): Each department's top members for a period, with informational totals.
- [List departments](https://developers.teambuilder.ge/api-reference/departments/list-departments.md): Your company's departments and their hierarchy, optionally including archived ones.
- [List shop items](https://developers.teambuilder.ge/api-reference/shop/list-shop-items.md): The rewards your employees can redeem, with your coin prices and stock.
- [Sync your employee roster](https://developers.teambuilder.ge/api-reference/roster-sync/sync-your-employee-roster.md): Upsert your HR roster in one idempotent request, optionally deactivating employees who have left.

## OpenAPI Specs

- [openapi](/api-reference/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.