---
title: "Request Custom Report"
method: POST
path: "/api/v1/reports/custom"
tags: ["Reports", "Public API"]
deprecated: true
---

# Request Custom Report

`POST /api/v1/reports/custom`

> **Deprecated.**

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

- `format` 'json' | 'xml' | 'csv' | 'xls' | 'pdf'
- `onlyCurrent` boolean

## Headers

- `Accept` 'application/json' | 'text/xml' | 'text/csv' | 'application/pdf' | 'application/vnd.ms-excel'

## Request body

- RequestCustomReport — Report definition for an ad-hoc custom report. Specify the fields to include and optionally filter the employee set. Field IDs are the internal BambooHR field names (e.g. `firstName`, `lastName`, `department`). See the fields metadata endpoint for available field IDs.
  - `title` string — A label for the report. Included in the response and used as the file name for downloaded reports.
  - `fields` string[] — Array of field IDs to include as columns in the report. Maximum of 400 fields.
  - `filters` object — Optional filters to restrict which employees appear in the report.
    - `lastChanged` object — Filters employees to those whose data was last changed on or after the given date/time.
      - `value` string, date-time — ISO 8601 date-time value. Only employees whose data has changed at or after this date-time will be included.
      - `includeNull` 'yes' | 'no' — Whether to include employees with no last-changed date. `yes` (default) includes them; `no` excludes them.
    - `employeeIds` integer[] — Restricts the report to only the specified internal employee IDs.
  - `filterDuplicates` 'yes' | 'no' — Whether to apply standard duplicate row filtering. Defaults to enabled. Set to `no` to return raw results without deduplication.

## Response `200`

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.

- object
  - `title` string — The report title.
  - `fields` object[] — Metadata for each field included in the report.
    - `id` string — The field ID.
    - `type` string — The field data type.
    - `name` string — The human-readable field label.
  - `employees` object[] — One object per employee. Each object contains an `id` property plus one key per requested field.
    - `id` string — The internal employee ID.

## Other 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`).

---

[API](https://skmtc.net/bamboohr/apis/bamboohr-api.md) · [All operations](https://skmtc.net/bamboohr/apis/bamboohr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bamboohr/bamboohr-api/revisions/19ebf391a399/schema)