# Sync employees

> Create or update employees in a batch with the FeedbackPulse REST API. Check the result for each employee.

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](https://feedbackpulse.com/help/developers/api.md#authentication) with the `employees:sync` scope.

## Example request

[Section titled “Example request”](#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.

```bash
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”](#example-response)

HTTP `200 OK`

```json
{
  "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”](#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”](#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”](#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”](#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”](#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](https://feedbackpulse.com/help/developers/api.md#errors) or [download the OpenAPI contract](https://feedbackpulse.com/help/developers/api/openapi-v1.yaml).
