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.
Example request
Section titled “Example request”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.
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" } ]}'Example response
Section titled “Example response”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": []}Request
Section titled “Request”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.
Headers
Section titled “Headers”| 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. |
JSON body
Section titled “JSON body”| 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. |
Response
Section titled “Response”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 |
Status codes
Section titled “Status codes”| 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.