---
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`

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.

---

[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)