v1
latestOpenAPI 3.1.02026-07-26294215839.4 KBRequest Custom Report
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 internal employee IDs). The maximum number of fields per request is 400.
OAuth Scopes: report
Query parameters
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.
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.
Headers
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.
Request body
Response
Report data in the requested format. For JSON, returns an object with a title string, a fields array (each with id, type, and name), and an employees array (each with id and one key per requested field). For XML, returns a <report> document. For CSV/XLS/PDF, returns the file content with the appropriate content-type header.