Create a bulk report batch

post

https://api.gusto-demo.com/v1/bulk_reports

Triggers asynchronous generation of up to 25 reports across companies the partner is mapped to. Each batch item is a custom_report (same parameters as create a custom report) or a general_ledger report (same parameters as create a general ledger report), keyed by company_uuid and report_type. Items are validated synchronously; if any is invalid, the entire batch is rejected.

Poll the bulk report GET endpoint with the returned uuid for status and the report URL, which is valid for 10 minutes.

📘 System Access Authentication

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

scope: company_reports:write

Body Params

Each batch item is a custom_report or a general_ledger report.

batch

array of objects

required

length between 1 and 25

One report per item. Up to 25 items per batch, across any combination of companies the partner is mapped to.

batch*

A custom report entry in a bulk batch.

company_uuid

uuid

required

UUID of the company to generate the report for. The partner must be mapped to this company.

report_type

string

enum

required

Identifies this batch item as a custom report.

Allowed:

columns

array of strings

required

Columns to include in the report.

columns*

groupings

array of strings

How to group the report. If omitted, defaults are derived from the requested columns.

groupings

Allowed:

file_type

string

enum

required

The type of file to generate.

Allowed:

custom_name

string

Display name for the report.

with_totals

boolean

Defaults to false

Whether to include subtotals and grand totals.

date_filter_type

string

enum

Defaults to period_end_date

Which payroll date start_date and end_date filter against.

Allowed:

start_date

date

Start date of data to filter by.

end_date

date

End date of data to filter by.

payment_method

string

enum

Payment method to filter by.

Allowed:

employment_type

string

enum

Employee employment type to filter by.

Allowed:

employment_status

string

enum

Employee employment status to filter by.

Allowed:

employee_uuids

array of strings | null

Employees to filter by.

employee_uuids

department_uuids

array of strings

Departments to filter by.

department_uuids

work_address_uuids

array of strings

Work addresses to filter by.

work_address_uuids

Headers

X-Gusto-API-Version

string

enum

Defaults to 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.

Allowed:

Responses

Language

Credentials

Bearer

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Created

422Unprocessable Entity This may happen when the body of your request contains errors such as invalid_attribute_value, or the request fails due to an invalid_operation. See the Errors Categories guide for more details.