Sign in

v1

latestOpenAPI 3.1.02026-07-243113441.2 MB
Reports

Create a custom report

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

post/v1/companies/{company_uuid}/reports

Path parameters

company_uuidstring required

The UUID of the company

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

columnsstring[] required

Columns to include in the report

groupingsstring[]

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

custom_namestring

The title of the report

file_type'csv' | 'json' | 'pdf' required

The type of file to generate

with_totalsboolean

Whether to include subtotals and grand totals in the report

date_filter_type'period_end_date' | 'period_start_date' | 'check_date'

Which payroll date start_date and end_date filter against.

start_datestring date

Start date of data to filter by

end_datestring date

End date of data to filter by

dismissed_start_datestring date

Dismissed start date of employees to filter by

dismissed_end_datestring date

Dismissed end date of employees to filter by

payment_method'check' | 'direct_deposit'

Payment method to filter by

employment_type'exempt' | 'salaried_nonexempt' | 'nonexempt' | 'commission_only_exempt' | 'commission_only_nonexempt'

Employee employment type to filter by

employment_status'active_full_time' | 'active_part_time' | 'active_part_time_eligible' | 'active_variable' | 'active_seasonal' | 'active' | 'dismissed'

Employee employment status to filter by

employee_uuidsstring[] nullable

Employees to filter by

department_uuidsstring[]

Departments to filter by

work_address_uuidsstring[]

Work addresses to filter by

Example request

{
  "start_date": "2024-01-01",
  "end_date": "2024-04-01",
  "dismissed_start_date": "2024-01-01",
  "dismissed_end_date": "2024-04-01"
}

Response

Created

request_uuidstring

A unique identifier of the report request

company_uuidstring

Company UUID

custom_namestring nullable

Title of the report

file_typestring

File type