v1

latestOpenAPI 3.1.02026-07-243113441.2 MB

People Batches

Create a people batch

Creates a batch for bulk employee creation.

The batch is processed asynchronously. Use the returned batch UUID to poll for status and results.

scope: people_batches:write

post/v1/companies/{company_id}/people_batches

Path parameters

company_idstring required

The UUID of the company

Headers

X-Gusto-API-Version'2026-06-15'

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Request body

idempotency_keystring uuid required

A unique identifier to ensure idempotency of the batch request

batch_action'create' required

The action to perform on the batch

Example request

{
  "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  "batch_action": "create",
  "batch": [
    {
      "entity_type": "employee"
    }
  ]
}

Response

created

uuidstring uuid required

The unique identifier of the people batch.

idempotency_keystring uuid required

The idempotency key provided when creating the batch.

status'pending' | 'processing' | 'completed' | 'failed' | 'partial_success' required

The current status of the batch processing.

batch_actionstring required

The action being performed on the batch.