Skip to content
Book a Demo

Sync employees

POST /v1/employees/sync

Synchronously creates or updates employees from a canonical batch payload. The response contains per-row actions, warnings, and summarized totals.

A row that would terminate the last active admin of the workspace is not applied. It is reported as errored with the code last_active_admin in errors, and the request still answers 200. A batch that terminates every admin therefore keeps one of them active. A refused row is stored with the rest of the response: a retry with the same Idempotency-Key replays it even after another admin exists, so retry with a new key.

Requires a workspace API-client key with the employees:sync scope.

Run this example in a test workspace. It creates or updates a record. Use a distinct idempotency key for each new sync and keep it the same when retrying that sync.

Terminal window
curl --request POST 'https://api.feedbackpulse.com/v1/employees/sync' \
--header "Authorization: Bearer $FEEDBACKPULSE_API_KEY" \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: example-hr:event-123' \
--data '{
"source": "example-hr",
"employees": [
{
"external_id": "hr-123",
"email": "alex@example.com",
"name": "Alex Example"
}
]
}'

HTTP 200 OK

{
"summary": {
"total": 1,
"created": 1,
"updated": 0,
"skipped": 0,
"errored": 0
},
"results": [
{
"row": 1,
"action": "created",
"employee_id": "emp_01J9EXAMPLE",
"email": "alex@example.com",
"warnings": []
}
],
"errors": []
}

Send a JSON object. Use the same source and external_id for the same employee across requests. A manager reference can use an external ID in the same source or a work email.

Header Required Description
Authorization Yes Bearer API-client key with employees:sync.
Content-Type Yes application/json
Idempotency-Key No Replays the original response when the same API client sends the same key and same request fingerprint to the same POST route. Rate-limited (429) and server error (5xx) responses are not stored, so retry them with the same key. A key whose request never finished returns 409 idempotency_key_in_progress for 10 minutes; after that, the next request with the same key and payload runs again.
Field Type Required Description
source string or null No Required when any employee row or manager reference uses external_id.
employees array Yes 1–100 items.
employees[].external_id string or null No
employees[].email string Yes Format: email.
employees[].name string or null No
employees[].employee_number string or null No
employees[].job_title string or null No
employees[].department string or null No
employees[].type string No Values: full-time, part-time, contractor.
employees[].employment_status string No Rehire never restores access or sends invitations. terminated is reported as an errored row with the code last_active_admin for the last active admin. Values: active, terminated.
employees[].send_invitation boolean No Explicit invitation command, rejected while access is disabled or account is activated. Default: false.
employees[].hire_date string or null No Format: date.
employees[].termination_date string or null No Format: date.
employees[].is_manager boolean No
employees[].manager null or object No Requires external_id or email.
employees[].manager.external_id string or null No
employees[].manager.email string or null No Format: email.

A 200 response can contain skipped or failed rows. Check each results[].action and match entries in errors using the one-based row number.

Field Type Required Description
summary object Yes
summary.total integer Yes
summary.created integer Yes
summary.updated integer Yes
summary.skipped integer Yes
summary.errored integer Yes
results array Yes
results[].row integer Yes
results[].action string Yes Values: created, updated, skipped, errored.
results[].employee_id string or null No
results[].email string Yes Format: email.
results[].warnings array Yes
errors array Yes
errors[].row integer Yes
errors[].code string Yes Machine-readable row error code, for example last_active_admin.
errors[].message string Yes
HTTP status Meaning
200 Sync completed
401 Missing or invalid bearer token
403 Authenticated but lacking the required API client scope
409 Idempotency key reused with a different request payload or still in progress
422 Validation failed or the idempotency key is invalid
429 Rate limit exceeded

See API errors and rate limits or download the OpenAPI contract.