Request Custom Report

post deprecated

https://{companyDomain}.bamboohr.com/api/v1/reports/custom

Deprecated. Use Datasets > Get Data from Dataset instead.

Generates an ad-hoc employee report based on a caller-specified list of fields and optional filters. Returns report data in the requested format (JSON, XML, CSV, XLS, or PDF). The report includes all employees regardless of status (both Active and Inactive), unlike the BambooHR UI which filters to Active employees by default.

The request body may be submitted as JSON or XML. To submit JSON, set Content-Type: application/json exactly — any variation such as application/json; charset=UTF-8 is not recognised as JSON and the body will be parsed as XML instead, which typically results in 400 Malformed XML. To submit XML, set Content-Type to any other value; the body must be a <report> document as described in the XML request body schema.

The format query parameter is case-insensitive (json, JSON, Json are all accepted). If format is omitted, the output format is inferred from the Accept header, but only these exact values are supported: application/json, text/xml, text/csv, application/pdf, application/vnd.ms-excel. Any other Accept value (including application/xml and */*) will return 404.

Field IDs in the request that are unknown or that the caller does not have permission to view are silently omitted from the report — the endpoint still returns 200. The filters object supports lastChanged (ISO 8601 date-time to filter employees by last-modified date, with optional includeNull control) and employeeIds (restrict results to specific employee IDs). The maximum number of fields per request is 400.

Query Params

format

string

enum

The output format for the report. Case-insensitive. If omitted, format is inferred from the Accept header — only application/json, text/xml, text/csv, application/pdf, and application/vnd.ms-excel are accepted; any other value returns 404.

Allowed:

onlyCurrent

boolean

Defaults to true

Whether to restrict historical fields to current values only. Set to false to include future-dated history values in the report output. Defaults to true.

Body Params

title

string

A label for the report. Included in the response and used as the file name for downloaded reports.

fields

array of strings

Array of field IDs to include as columns in the report. Maximum of 400 fields.

fields

filters

object

Optional filters to restrict which employees appear in the report.

filterDuplicates

string

enum

Whether to apply standard duplicate row filtering. Defaults to enabled. Set to no to return raw results without deduplication.

Allowed:

Headers

string

enum

The desired response content type when format is omitted. Accepted values: application/json, text/xml, text/csv, application/pdf, application/vnd.ms-excel. Any other value returns 404.

Allowed:

Responses

400

Bad request. Returned when the request body is malformed JSON or XML, or when more than 400 fields are requested. Unknown or inaccessible field IDs are silently omitted and do not cause a 400.

404

Report format not found. Returned when an unsupported format value is supplied (e.g. ?format=bogus), or when format is omitted and the Accept header is not one of the supported exact values (application/json, text/xml, text/csv, application/pdf, application/vnd.ms-excel).