---
title: "Create a custom report"
method: POST
path: "/v1/companies/{company_uuid}/reports"
tags: ["Reports"]
---

# Create a custom report

`POST /v1/companies/{company_uuid}/reports`

## Request

- Base URL: `https://api.gusto-demo.com`
- URL: `https://api.gusto-demo.com/v1/companies/{company_uuid}/reports`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/gusto/apis/gusto-api/docs/v1/companies/:company_uuid/reports/post.ts> (a function with typed inputs; its response is checked against the schema)

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](https://docs.gusto.com/embedded-payroll/reference/get-reports-request_uuid). This URL is valid for 10 minutes.

scope: `company_reports:write`

## Path parameters

- `company_uuid` string, required

## Headers

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

## Request body

- CreateReportBody: Request body for creating a custom report.
  - `columns` string[], required: Columns to include in the report
  - `groupings` string[]: Optional. How to group the report. If omitted, sensible defaults are derived from the `columns` requested.
  - `custom_name` string: The title of the report
  - `file_type` 'csv' | 'json' | 'pdf', required: The type of file to generate
  - `with_totals` boolean: 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_date` string, date: Start date of data to filter by
  - `end_date` string, date: End date of data to filter by
  - `dismissed_start_date` string, date: Dismissed start date of employees to filter by
  - `dismissed_end_date` string, 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_uuids` string[], nullable: Employees to filter by
  - `department_uuids` string[]: Departments to filter by
  - `work_address_uuids` string[]: Work addresses to filter by

## Response `201`

Created

- CreateReport
  - `request_uuid` string: A unique identifier of the report request
  - `company_uuid` string: Company UUID
  - `custom_name` string, nullable: Title of the report
  - `file_type` string: File type

## Other responses

- `404`: Not Found The requested resource does not exist. Make sure the provided UUID is valid.
- `422`: Unprocessable 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](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.

## Changes

- **2026-11-03** `f98575fa2a5e`: 2 info
  - added the new `additional_earnings` enum value to the request property `columns/items/`
  - added the new `employee_state_income_tax` enum value to the request property `columns/items/`

[Operation history](https://skmtc.dev/gusto/apis/gusto-api/changes/v1/companies/:company_uuid/reports/post.md)

---

[API](https://skmtc.dev/gusto/apis/gusto-api.md) - [All operations](https://skmtc.dev/gusto/apis/gusto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gusto/apis/gusto-api/revisions/f98575fa2a5e?raw)