Create a custom report

post

https://api.gusto-demo.com/v1/companies/{company_uuid}/reports

Create a custom report for a company. This endpoint initiates creating a custom report with custom columns, groupings, and filters. The request_uuid in the response can then be used to poll for the status and report URL upon completion using the report GET endpoint. This URL is valid for 10 minutes.

scope: company_reports:write

Path Params

company_uuid

string

required

The UUID of the company

Body Params

columns

array of strings

required

Columns to include in the report

columns*

groupings

array of strings

required

How to group the report

groupings*

custom_name

string

The title of the report

file_type

string

enum

required

The type of file to generate

Allowed:

with_totals

boolean

Defaults to false

Whether to include subtotals and grand totals in the report

start_date

date

Start date of data to filter by

end_date

date

End date of data to filter by

dismissed_start_date

date

Dismissed start date of employees to filter by

dismissed_end_date

date

Dismissed end date of employees 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-02-01

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

404

Not Found

The requested resource does not exist. Make sure the provided UUID is valid.

200Example response

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.