# Reports

URL: https://submitator.com/docs/api/reports

> PDF and XLSX reports of a project's listings, prepared under your agency's name.

PDF and XLSX reports of a project's listings, prepared under your agency's name. Build one, wait until it is `ready`, and download it within 7 days.

Send `include_logins: true` to add the directory logins and their password, for your client to take over the accounts. Such a report never appears on a share link's page, and only a key with full permissions downloads it.

## Build a report

`POST https://api.submitator.com/v1/projects/{project_id}/reports`

Starts building a PDF or XLSX report of the project's listings, prepared under your agency's name, with the directory logins when you send `include_logins: true`. Poll the report until `status` is `ready`, or wait for the `report.ready` event. Each project can start 1 PDF every 30 seconds and 1 XLSX every 10 seconds, and as many again with logins.

| Parameter | In | Required | What it is |
| --- | --- | --- | --- |
| `project_id` | path | Yes | The project's id. |
| `Idempotency-Key` | header | No | A unique string, such as a UUID, that makes a retry safe. A success is kept for 24 hours: a repeat with the same key and body returns it again with `Idempotent-Replayed: true`, and the same key with another body returns 422 `idempotency_key_reused`. A repeat while the first request runs returns 409 `idempotency_key_in_use`. An error changes nothing, so a repeat after one runs again. |

| Body field | Type | Required | What it is |
| --- | --- | --- | --- |
| `format` | string | Yes | `pdf` for a document to forward, `xlsx` for a spreadsheet with 1 row per listing. |
| `include_logins` | boolean | No | `true` to add the directory logins and the password they share: a page in the PDF, a sheet in the XLSX. Such a report never appears on a share link's page, and only a key with full permissions downloads its file. Defaults to `false`. |

Request:

```json
{
  "format": "pdf"
}
```

Response 202:

```json
{
  "object": "report",
  "id": "rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP",
  "livemode": false,
  "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
  "format": "pdf",
  "include_logins": false,
  "status": "building",
  "file_name": null,
  "created_at": "2026-10-08T15:02:10Z",
  "ready_at": null,
  "expires_at": null
}
```

Typical errors: [`validation_failed`](https://submitator.com/docs/errors#validation_failed), [`rate_limited`](https://submitator.com/docs/errors#rate_limited), [`not_found`](https://submitator.com/docs/errors#not_found).

## Read a report

`GET https://api.submitator.com/v1/reports/{report_id}`

Returns the report and its status. Once `status` is `ready`, download the file from `GET /reports/{report_id}/file` until `expires_at`.

| Parameter | In | Required | What it is |
| --- | --- | --- | --- |
| `report_id` | path | Yes | The report's id. |

Response 200:

```json
{
  "object": "report",
  "id": "rep_6Hn2Wq8Lx3Kt9Vb5Rz1MdP",
  "livemode": false,
  "project": "prj_4QzX1m9Lr2Vb7Nc8Tk3HwP",
  "format": "pdf",
  "include_logins": false,
  "status": "ready",
  "file_name": "ledgerly-listings-2026-10-08.pdf",
  "created_at": "2026-10-08T15:02:10Z",
  "ready_at": "2026-10-08T15:02:41Z",
  "expires_at": "2026-10-15T15:02:41Z"
}
```

Typical errors: [`not_found`](https://submitator.com/docs/errors#not_found), [`rate_limited`](https://submitator.com/docs/errors#rate_limited).

## Download a report file

`GET https://api.submitator.com/v1/reports/{report_id}/file`

Returns the PDF or XLSX file of a ready report. Files are kept for 7 days; after `expires_at` this returns 410 `gone`, and you build a new report. A file with logins is credentials: a read-only key gets 403 `permission_denied` for it.

| Parameter | In | Required | What it is |
| --- | --- | --- | --- |
| `report_id` | path | Yes | The report's id. |

Typical errors: [`gone`](https://submitator.com/docs/errors#gone), [`not_found`](https://submitator.com/docs/errors#not_found).