Sign in

v1

latestOpenAPI 3.1.02026-07-243113441.2 MB
Payroll Digests

Get a payroll digest batch

Returns the status and results of a payroll digest batch.

Poll this endpoint until the batch status reaches a terminal value (completed or failed). Once terminal, the response includes the full results array (one entry per attempted company, each with its own per-company status — success, partial_success, or failed) and the exclusions array (one entry per company that could not be looked up or processed).

Note that the top-level batch status (pending / processing / completed / failed) is distinct from the per-company status returned inside results[] and exclusions[]. A completed batch does not imply every company succeeded — inspect the arrays for per-company outcomes.

Results are stored in Redis with a short TTL after completion. If the partner polls after results have expired, this endpoint returns 410 Gone — partners should re-submit a new batch to fetch fresh data.

📘 System Access Authentication

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

scope: payroll_digests:read

get/v1/payroll_digests/{payroll_digest_uuid}

Path parameters

payroll_digest_uuidstring required

The UUID of the payroll digest batch returned by 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.

Response

successful

uuidstring uuid required

The unique identifier of the payroll digest batch.

idempotency_keystring uuid required

The idempotency key provided when creating 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[].

submitted_atstring date-time required

The timestamp when the batch was submitted.

completed_atstring date-time nullable

The timestamp when the batch processing completed.

submitted_itemsinteger nullable

The number of companies submitted in the batch.

processed_itemsinteger

The number of companies successfully processed. Only present once the batch reaches a terminal status.

excluded_itemsinteger

The number of companies excluded from processing. Only present once the batch reaches a terminal status.