---
title: "Create a payroll digest batch"
method: POST
path: "/v1/payroll_digests"
tags: ["Payroll Digests"]
---

# Create a payroll digest batch

`POST /v1/payroll_digests`

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](https://docs.gusto.com/embedded-payroll/docs/system-access)

scope: `payroll_digests:write`

## Headers

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

## Request body

- object
  - `idempotency_key` string, 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.
  - `batch` object[], required — Array of companies to fetch payroll digest data for. Maximum 25 companies per request.
    - `entity_type` 'company', required — The type of entity to look up.
    - `uuid` string, uuid, required — The UUID of a company that the partner is mapped to. Companies that the partner is not authorized to access will appear in the response's `exclusions` array.

## Response `201`

created

- PayrollDigest — A payroll digest batch request.
  - `uuid` string, uuid, required — The unique identifier of the payroll digest batch.
  - `idempotency_key` string, 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[]`.

## Other responses

- `409` — conflict - idempotency key already used by this partner
- `422` — unprocessable entity - validation errors

---

[API](https://skmtc.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)