Skip to main content
PUT
Sync your employee roster
Read the roster sync guide before your first run: it covers matching, departments, deactivation guards, chunking and a worked example.

Authorizations

​
Authorization
string
header
required

API key — tb_live_… for production data, tb_test_… for the sandbox.

Body

application/json

Your employee roster, or one part of it.

​
employees
object[]
required

The employees to sync, at most 5,000 per request. Each row is checked on its own: an invalid row is reported in errors and does not stop the others.

Required array length: 1 - 5000 elements
​
deactivate_missing
boolean
default:false

Set to true to deactivate the employees this request does not name. Send it only when the request carries your complete roster; leave it false when you split a roster across requests. Only employees linked to an external_id can be deactivated (the others are counted in unlinked_members), and never admins. Nobody is deactivated when any row is rejected as malformed, duplicated or outside your SSO domains, when the sync stopped part-way (batch_aborted), or when more employees would be deactivated than deactivation_limit allows (see max_deactivations). Deactivation is soft: history is kept, and a later sync that names the employee again reactivates them.

Example:

true

​
max_deactivations
integer

Confirms a large deactivation. Without it, one sync deactivates at most 10 employees or 20% of your active employees linked to an external_id (admins excluded), whichever is more; with it, at most this many. Send it only for a deliberate reorganisation. If more employees would be deactivated, nobody is, and deactivation_skipped_reason says why.

Required range: 1 <= x <= 100000
Example:

25

Response

The sync ran. Check errors for rows that were not applied.

What the sync did. created + updated + unchanged plus the number of errors equals the rows sent.

​
created
integer
required

Employees added to your company.

Required range: x >= 0
Example:

3

​
updated
integer
required

Existing employees whose external_id, department or job title changed, or who were reactivated.

Required range: x >= 0
Example:

5

​
unchanged
integer
required

Rows that already matched TeamBuilder. Sending the same roster again reports every row here.

Required range: x >= 0
Example:

205

​
reactivated
integer
required

Of updated: deactivated employees this roster named again, now active.

Required range: x >= 0
Example:

1

​
deactivated
integer
required

Employees deactivated because deactivate_missing was true. 0 otherwise.

Required range: x >= 0
Example:

2

​
departments_created
integer
required

Departments created, at the top level, because a row named an unknown one.

Required range: x >= 0
Example:

1

​
departments_restored
integer
required

Archived departments restored because a row named their department_external_id.

Required range: x >= 0
Example:

0

​
deactivation_candidates
object[]
required

Active employees linked to an external_id that this roster does not name, ordered by employee_id, at most 1,000. They were deactivated if deactivate_missing was true and deactivation_skipped_reason is null; otherwise they are only reported. Admins and employees with an admin-portal role are never candidates.

Example:
​
deactivation_candidates_total
integer
required

All deactivation candidates, including any beyond the ones listed.

Required range: x >= 0
Example:

2

​
unlinked_members
integer
required

Active employees without an external_id (added in TeamBuilder, never synced) that this roster does not name. A sync never deactivates them. To link one, send their email with an external_id.

Required range: x >= 0
Example:

4

​
deactivation_limit
integer
required

The most employees this sync could deactivate: max_deactivations if you sent it, else the default limit.

Required range: x >= 0
Example:

25

​
deactivation_skipped_reason
enum<string> | null
required

Why deactivate_missing deactivated nobody. Null when it was not requested or nothing stopped it.

  • rejected_rows: some rows were malformed, duplicated or outside your SSO domains, or the sync stopped part-way, so the roster may be incomplete.
  • limit_exceeded: more employees would have been deactivated than deactivation_limit allows; send max_deactivations to confirm.
Available options:
rejected_rows,
limit_exceeded
Example:

null

​
errors
object[]
required

Rows that were not applied, in request order.

​
warnings
object[]
required

Rows that were applied but deserve a look, in request order.