v1

latestOpenAPI 3.1.02026-07-243113441.2 MB

Payroll Digests

Create a payroll digest batch

Triggers an asynchronous computation of payroll digest data (statuses, blockers, pay periods, totals) across up to 25 companies that the partner is mapped to.

The batch is processed asynchronously. Use the returned batch UUID to poll GET /v1/payroll_digests/{payroll_digest_uuid} for status and results.

Idempotency is scoped per (partner, idempotency_key). A duplicate POST with the same idempotency_key returns a 409 Conflict referencing the existing batch UUID — no duplicate computation occurs.

📘 System Access Authentication

This endpoint uses the Bearer Auth scheme with the system-level access token in the HTTP Authorization header

scope: payroll_digests:write

post/v1/payroll_digests

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 partner-generated unique identifier to ensure idempotency of the batch request. Scoped per partner.

batch_action'create' required

The action to perform on the batch.

Example request

{
  "idempotency_key": "80a74f8b-2c16-45e5-9038-aa108849c6e6",
  "batch_action": "create",
  "batch": [
    {
      "entity_type": "company"
    }
  ]
}

Response

created

uuidstring uuid required

The unique identifier of the payroll digest batch.

idempotency_keystring uuid required

The idempotency key provided when creating the batch.

batch_action'create' required

The action being performed on the batch.

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

The lifecycle status of the batch request itself. Terminal values are completed (processing finished — inspect results and exclusions for per-company outcomes) and failed (request failed; can be retried). This is distinct from the per-company status returned inside results[] and exclusions[].