Reports: statements, balance certificates and bank letters

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

You call POST /v1/reports. The report is created with status PENDING and generated in the background, usually within seconds.
You learn when it is done, in one of two ways:
- Listen for the report.ready and report.failed webhooks.
- Poll GET /v1/reports/{reportId} until status is READY or FAILED.
Once READY, you call GET /v1/reports/{reportId}/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

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"
  }'

{
  "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

{
  "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

{
  "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.

Download the file

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 returns your organization’s reports, newest first, with the usual limit and cursor 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, 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.

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 for the format.

Getting started

Core concepts

Guides

Reports: statements, balance certificates and bank letters

Report types

How it works

Request a statement

Request a balance certificate

Request a bank confirmation letter

Download the file

List reports

Limits

Reports for your clients

Errors

​Report types

​How it works

​Request a statement

​Request a balance certificate

​Request a bank confirmation letter

​Download the file

​List reports

​Limits

​Reports for your clients

​Errors

Report types

How it works

Request a statement

Request a balance certificate

Request a bank confirmation letter

Download the file

List reports

Limits

Reports for your clients

Errors