> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nxos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports: statements, balance certificates and bank letters

> Request account and transaction statements, balance certificates and bank confirmation letters through the API, then download the file once it is ready.

This guide explains how to get your organization's documents through the API: the same statements, certificates and letters you can download from the dashboard.

## Report types

| `type` | What it holds | Formats | Covers |
| - | - | - | - |
| `ACCOUNT_STATEMENT` | Opening and closing balances, with every completed transaction of the period. | `PDF`, `CSV` | `from` to `to` |
| `TRANSACTION_STATEMENT` | Every transaction of the period, whatever its status. | `PDF`, `CSV` | `from` to `to` |
| `BALANCE_CERTIFICATE` | The balances held at the end of one day. | `PDF` | `asOf` |
| `BANK_CONFIRMATION_LETTER` | A letter confirming the bank account one of your funding methods receives on. | `PDF` | One funding method and asset |

Statements and certificates cover every currency by default. Pass `currency` (an asset code such as `USD`) to cover one currency only.

## How it works

1. You call [`POST /v1/reports`](https://docs.nxos.io/api-reference/reports/create). The report is created with status `PENDING` and generated in the background, usually within seconds.
2. You learn when it is done, in one of two ways:
   * Listen for the [`report.ready` and `report.failed` webhooks](https://docs.nxos.io/concepts/webhooks#event-catalog).
   * Poll [`GET /v1/reports/{reportId}`](https://docs.nxos.io/api-reference/reports/get) until `status` is `READY` or `FAILED`.
3. Once `READY`, you call [`GET /v1/reports/{reportId}/download`](https://docs.nxos.io/api-reference/reports/download), which redirects to the file.

| `status` | Meaning |
| - | - |
| `PENDING`, `PROCESSING` | Being generated. |
| `READY` | The file can be downloaded. `fileName`, `sizeBytes` and `readyAt` are set. |
| `FAILED` | The report could not be generated. Request it again. |

## Request a statement

```bash theme={null}
curl https://api.sandbox.nxos.io/v1/reports \
  -X POST \
  -H "Authorization: Bearer nxos_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ACCOUNT_STATEMENT",
    "format": "PDF",
    "from": "2026-09-01",
    "to": "2026-09-30",
    "currency": "USD"
  }'
```

```json theme={null}
{
  "object": "report",
  "reportId": "rpt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "type": "ACCOUNT_STATEMENT",
  "format": "PDF",
  "status": "PENDING",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "asOf": null,
  "currency": "USD",
  "fileName": null,
  "sizeBytes": null,
  "createdAt": "2026-10-01T09:12:44.000Z",
  "readyAt": null
}
```

* Dates are days in UTC, as `YYYY-MM-DD`. `to` is inclusive.
* `from` can be no earlier than `2024-01-01`, and the period can be at most 366 days long.
* A period reaching today runs up to the moment of the request.

## Request a balance certificate

```json theme={null}
{
  "type": "BALANCE_CERTIFICATE",
  "asOf": "2026-09-30"
}
```

The certificate states the balances at the end of `asOf`. The day must have ended: a certificate for today is refused with `invalid_request`.

## Request a bank confirmation letter

```json theme={null}
{
  "type": "BANK_CONFIRMATION_LETTER",
  "fundingMethodId": "funding_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "asset": "EUR"
}
```

The funding method must be a `BANK` funding method of your organization, with `asset` enabled on it. List them with [`GET /v1/funding-methods`](https://docs.nxos.io/api-reference/funding-methods/list).

## Download the file

```bash theme={null}
curl -L -o statement.pdf \
  https://api.sandbox.nxos.io/v1/reports/rpt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4/download \
  -H "Authorization: Bearer nxos_sk_test_..."
```

The endpoint answers `303 See Other` with a `Location` header holding a signed link to the file. The link expires after one minute:

* Follow the redirect straight away (`curl -L`, or your HTTP client's default redirect handling).
* Do not store the link. Call the download endpoint again whenever you need the file.

Downloading a report that is not `READY` returns `409 report_not_ready`.

## List reports

[`GET /v1/reports`](https://docs.nxos.io/api-reference/reports/list) returns your organization's reports, newest first, with the usual `limit` and `cursor` [pagination](https://docs.nxos.io/concepts/conventions.md#pagination). The list includes every report of your organization: the ones requested through the API, the ones requested on the dashboard, and the monthly statements nxos generates for you.

## Limits

* Requesting a report needs your organization to be verified (`APPROVED`). Listing, retrieving and downloading do not.
* Up to 5 reports can be in progress at once per organization. A sixth request returns `409 too_many_pending_reports`: wait for one to finish.
* `POST /v1/reports` accepts an [`Idempotency-Key`](https://docs.nxos.io/concepts/idempotency-and-rate-limits), so a retried request does not create a second report.

## Reports for your clients

A broker can work on a client's reports with the `Nxos-On-Behalf-Of` header. See [Cross-org access](https://docs.nxos.io/guides/cross-org-access.md).

* **Requesting** needs an active Letter of Authorization, and the client must be `APPROVED`. The report belongs to the client: it appears in the client's list and on the client's dashboard.
* **Listing, retrieving and downloading** accept any Letter of Authorization the client has not revoked, whatever the client's verification status.

Webhooks for a client's reports reach the broker's endpoints only once the client has signed the Letter of Authorization.

## Errors

| Code | HTTP | What to do |
| - | - | - |
| `invalid_request` | 400 | A date is malformed, the period is out of range, the day has not ended yet, or the currency is not supported. The `message` says which. |
| `verification_required` | 403 | Your organization (or the client you act for) is not verified yet. |
| `funding_method_not_found` | 404 | The funding method does not belong to your organization, or cannot be confirmed in a letter. |
| `report_not_found` | 404 | The report does not exist or does not belong to your organization. |
| `report_not_ready` | 409 | The report is still being generated, or failed. Download it once `status` is `READY`. |
| `too_many_pending_reports` | 409 | 5 reports are already being generated. Request more once they are ready. |
| `validation_error` | 422 | The body does not match any report request. Check `type` and the fields it needs. |

See [Errors](https://docs.nxos.io/concepts/errors.md) for the format.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.