Sandbox and testing

Every customer gets a private sandbox company. A tb_test_ key reads and writes the sandbox instead of your real company, through the same endpoints, scopes, limits and response shapes. Going live means swapping the key, nothing else.

curl https://api.teambuilder.ge/v1/ping -H "Authorization: Bearer $TEAMBUILDER_TEST_KEY"

Response

{
  "company_id": "0b6c1e2f-4a8d-4f3e-9b71-6d2e8c5a1f04",
  "key_prefix": "tb_test_",
  "scopes": ["employees:read", "leaderboard:read", "departments:read", "shop:read"],
  "mode": "test"
}

What the sandbox contains

The sandbox is created and seeded when your first test key is issued. It is shaped so every endpoint has something meaningful to return:

Data	Seeded with
Departments	Engineering (with a Frontend sub-department), Sales, Marketing, and People & Culture, each with an `external_id` such as `SBX-DEP-ENG`.
Employees	Eleven active employees spread across those departments (one has no department), plus one deactivated employee who never appears in responses. External ids look like `SBX-E001`.
XP	Earned at different times over the past year and more, so `this_month`, `last_3_months`, `last_year` and `all_time` leaderboards rank people differently.
Coins and badges	Balances and badges per employee, for profile widgets.
Shop	Four items with sandbox prices and limited stock, for the shop catalogue.

Sandbox employees have non-deliverable addresses on a .invalid domain, so nobody can sign in as them and no email can ever reach them. The sandbox is excluded from TeamBuilder’s analytics and does not appear in your company’s TeamBuilder portal.

Testing roster sync

Test keys with the employees:write scope sync into the sandbox. Use them to rehearse your real export before the first live run:

Emails you send are stored as non-deliverable stand-ins, so real addresses are never kept in the sandbox and nobody is contacted. Because of this, look up synced sandbox employees by external_id, not email, and expect email fields in sandbox responses (including deactivation_candidates) to be stand-ins. Names, job titles, HR ids and department names are stored as you send them.
Your SSO domain restriction does not apply.
The sandbox holds at most 500 employees; rows that would add more fail with sandbox_limit_reached. Trim large exports for test runs.
Every other rule (matching, departments, deactivation guards, idempotency, rate limits) behaves exactly as in live.

Sandbox data persists between runs and is not reset automatically. If you need a fresh sandbox, ask us.

The API playground

The Try it panel on each API reference page sends real requests.

Playground requests are relayed through the servers of Mintlify, the platform that hosts this documentation, so a key you paste there leaves your machine. Use only tb_test_ keys in the playground. If a live key was ever pasted there, rotate it.

Moving to live

Get your live key

Ask contact@teambuilder.ge for a tb_live_ key with the same scopes.

Swap the secret

Replace the test key in your production secret manager. Keep the test key in development and staging.

Assert the mode

On start-up, call GET /v1/ping and fail fast if mode is not what that environment expects.

Re-resolve ids

Sandbox employee_id and department id values do not exist in your live company. Clear any cached ids and resolve them again with live data.

Getting started

Guides

Reference

What the sandbox contains

Testing roster sync

The API playground

Moving to live

​What the sandbox contains

​Testing roster sync

​The API playground

​Moving to live

What the sandbox contains

Testing roster sync

The API playground

Moving to live