People batch webhooks

There are two event types for the :

event_type	event_description
people_batch.completed	The batch has completed processing. This will be emitted on both full success, and partial success. Call the batch status endpoint for details how external_id correlates to employee uuid, and to check for any partial failures
people_batch.failed	The entire batch did not process for some internal reason. Call the batch status endpoint for details.

1. Receive a webhook

After you submit a people batch, you will eventually receive a webhook when the batch is done processing.

Regardless of the webhook’s event type, you’ll need to retrieve the status of the people batch.

people_batch.completed

The people_batch.completed webhook is sent for either full or partial successes, with a payload that looks like the following example:

Example payload

{
  "uuid": "03ffbf0c-48a9-4f1c-932a-546413a26ad1",
  "event_type": "people_batch.completed",
  "resource_type": "Company",
  "resource_uuid": "5df911a0-e8e9-412d-8aaf-a46ad193dd96",
  "entity_type": "PeopleBatch",
  "entity_uuid": "bcfc9744-0ab3-4ef3-ab0d-e728255d659c",
  "timestamp": 1671058841,
  "references": {
     "batch_uuid": "bcfc9744-0ab3-4ef3-ab0d-e728255d659c" # this is the batch_id that was provided in the results of the upload
  }
}

people_batch.failed

If you receive the people_batch.failed webhook, none of the items were processed due to an internal system error.

Example payload

{
  "uuid": "03ffbf0c-48a9-4f1c-932a-546413a26ad1",
  "event_type": "people_batch.failed",
  "resource_type": "Company",
  "resource_uuid": "5df911a0-e8e9-412d-8aaf-a46ad193dd96",
  "entity_type": "PeopleBatch",
  "entity_uuid": "bcfc9744-0ab3-4ef3-ab0d-e728255d659c",
  "timestamp": 1671058841,
  "references": {
    "batch_uuid": "bcfc9744-0ab3-4ef3-ab0d-e728255d659c"
  }
}

2. Retrieve the batch status

Call GET /v1/people_batches/{batch_uuid} to retrieve the status of the batch. For more information, see Get the status of a people batch.

Full success

The status will be "success", and the number of submitted_items will be equal to the number of processed_items.

For each of the batch records, you’ll need to retrieve the employee_uuid to correlate it to the external_id you have for that employee.

Partial success

The status will be "partial_success", and there will be fewer processed_items than submitted_items.

We will provide the status (success or failure) for each attribute for a given employee. When an attribute or person has a partial failure, the original operation (create or update) can be safely retried as part of a new batch request.

Failure

The status is "failed" meaning none of the items in the batch were processed.

---

Get the status of a people batch

Manage contractors