> ## 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. # Request a report > Request a report. It is generated in the background: the response is the report with status `PENDING`. Poll `GET /v1/reports/{reportId}`, or listen for the `report.ready` and `report.failed` webhooks, then download it. Up to 5 reports can be in progress at once per organization. Supports `Nxos-On-Behalf-Of` to request a report on a client, with an active letter of authorization. The report then belongs to the client. ## OpenAPI ````yaml POST /v1/reports openapi: 3.0.0 info: title: nxos API version: 1.0.0 contact: name: nxos url: https://nxos.io description: |- The nxos platform API provides programmatic access to accounts, balances, quotes, and trades. All endpoints require API key authentication. servers: - url: https://api.nxos.io description: Production variables: {} - url: https://api.sandbox.nxos.io description: Sandbox variables: {} security: [] tags: - name: Accounts - name: Quotes - name: Beneficiaries - name: Fiat Payouts - name: Crypto Payouts - name: Sandbox Faucet - name: Nxosnet - name: Fees - name: Sub-Org Tiers - name: Assets - name: Funding Methods - name: Transactions - name: Organizations - name: Authorizations - name: Referral invites - name: Referral links - name: Reports - name: Webhooks description: >- Register an HTTPS endpoint to receive events (organization verification, transaction status changes, and finished reports) instead of polling. Deliveries are signed; verify the `svix-signature` header before acting on an event. See the [Webhooks guide](https://docs.nxos.io/core-concepts/webhooks) for the delivery format, signature verification, retries, and broker behavior. Payload shapes are documented in the `…Event` models below. paths: /v1/reports: post: tags: - Reports description: >- Request a report. It is generated in the background: the response is the report with status `PENDING`. Poll `GET /v1/reports/{reportId}`, or listen for the `report.ready` and `report.failed` webhooks, then download it. Up to 5 reports can be in progress at once per organization. Supports `Nxos-On-Behalf-Of` to request a report on a client, with an active letter of authorization. The report then belongs to the client. operationId: Reports_create parameters: - $ref: '#/components/parameters/ApiKeyAuth' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateReportRequest' responses: '201': description: >- The request has succeeded and a new resource has been created as a result. content: application/json: schema: $ref: '#/components/schemas/Report' '400': description: The server could not understand the request due to invalid syntax. content: application/json: schema: $ref: '#/components/schemas/Error400' examples: 'invalid_request: Dates must be YYYY-MM-DD.': summary: 'invalid_request: Dates must be YYYY-MM-DD.' value: error: code: invalid_request message: Dates must be YYYY-MM-DD. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'invalid_request: Period starts too far back.': summary: 'invalid_request: Period starts too far back.' value: error: code: invalid_request message: Period starts too far back. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'invalid_request: Period has not started yet.': summary: 'invalid_request: Period has not started yet.' value: error: code: invalid_request message: Period has not started yet. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'invalid_request: Period is longer than a year.': summary: 'invalid_request: Period is longer than a year.' value: error: code: invalid_request message: Period is longer than a year. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'invalid_request: Date must be YYYY-MM-DD.': summary: 'invalid_request: Date must be YYYY-MM-DD.' value: error: code: invalid_request message: Date must be YYYY-MM-DD. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'invalid_request: Pick a day that has already ended.': summary: 'invalid_request: Pick a day that has already ended.' value: error: code: invalid_request message: Pick a day that has already ended. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'invalid_request: Date is too far back.': summary: 'invalid_request: Date is too far back.' value: error: code: invalid_request message: Date is too far back. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'invalid_request: That currency is not supported.': summary: 'invalid_request: That currency is not supported.' value: error: code: invalid_request message: That currency is not supported. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'invalid_request: Idempotency-Key must be 1–255 characters.': summary: 'invalid_request: Idempotency-Key must be 1–255 characters.' value: error: code: invalid_request message: Idempotency-Key must be 1–255 characters. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'invalid_request: Content-Type must be application/json.': summary: 'invalid_request: Content-Type must be application/json.' value: error: code: invalid_request message: Content-Type must be application/json. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'invalid_request: Malformed JSON in request body.': summary: 'invalid_request: Malformed JSON in request body.' value: error: code: invalid_request message: Malformed JSON in request body. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 '401': description: Access is unauthorized. content: application/json: schema: $ref: '#/components/schemas/Error401' '403': description: Access is forbidden. content: application/json: schema: $ref: '#/components/schemas/Error403' examples: 'verification_required: Complete identity verification before using the API.': summary: >- verification_required: Complete identity verification before using the API. value: error: code: verification_required message: Complete identity verification before using the API. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 acting_org_not_found: summary: acting_org_not_found value: error: code: acting_org_not_found message: >- Nxos-On-Behalf-Of points to an organization that does not exist. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 authorization_required: summary: authorization_required value: error: code: authorization_required message: No active authorization for the requested organization. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 'verification_required: Complete identity verification before moving funds or managing clients': summary: >- verification_required: Complete identity verification before moving funds or managing clients value: error: code: verification_required message: >- Complete identity verification before moving funds or managing clients and recipients. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/Error404' examples: funding_method_not_found: summary: funding_method_not_found value: error: code: funding_method_not_found message: That account cannot be confirmed in a letter. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 '409': description: The request conflicts with the current state of the server. content: application/json: schema: $ref: '#/components/schemas/Error409' examples: too_many_pending_reports: summary: too_many_pending_reports value: error: code: too_many_pending_reports message: >- A few reports are still being generated. Try again once they are ready. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 idempotency_request_in_flight: summary: idempotency_request_in_flight value: error: code: idempotency_request_in_flight message: >- A request with this Idempotency-Key is currently being processed. Retry shortly. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 idempotency_key_in_use: summary: idempotency_key_in_use value: error: code: idempotency_key_in_use message: >- This Idempotency-Key was previously used with a different request body. Use a unique key per logical operation. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 '422': description: Client error content: application/json: schema: $ref: '#/components/schemas/Error422' examples: validation_error: summary: validation_error value: error: code: validation_error message: Request body failed validation. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 '429': description: Client error content: application/json: schema: $ref: '#/components/schemas/Error429' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error500' components: parameters: ApiKeyAuth: name: Authorization in: header required: true description: 'Bearer token. Format: `Bearer `' schema: type: string IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Unique key per logical operation. UUID v4 recommended. Max 255 characters. schema: type: string schemas: CreateReportRequest: anyOf: - $ref: '#/components/schemas/CreateStatementRequest' - $ref: '#/components/schemas/CreateBalanceCertificateRequest' - $ref: '#/components/schemas/CreateBankConfirmationLetterRequest' description: A report request, discriminated by `type`. Report: type: object required: - object - reportId - type - format - status - from - to - asOf - currency - fileName - sizeBytes - createdAt - readyAt properties: object: type: string enum: - report description: Object type. Always `report`. reportId: type: string description: Report identifier. type: allOf: - $ref: '#/components/schemas/ReportType' description: The kind of document. format: allOf: - $ref: '#/components/schemas/ReportFormat' description: File format. status: allOf: - $ref: '#/components/schemas/ReportStatus' description: Where the report stands. Download it once `READY`. from: type: string nullable: true description: >- First day covered (`YYYY-MM-DD`, UTC) for a statement; `null` otherwise. to: type: string nullable: true description: >- Last day covered, inclusive (`YYYY-MM-DD`, UTC) for a statement; `null` otherwise. asOf: type: string nullable: true description: >- The day whose closing balances a certificate states (`YYYY-MM-DD`, UTC); `null` for other reports. currency: type: string nullable: true description: >- The one currency covered, or `null` when the report covers every currency. fileName: type: string nullable: true description: File name, once `READY`. sizeBytes: type: integer format: int32 nullable: true description: File size in bytes, once `READY`. createdAt: allOf: - $ref: '#/components/schemas/dateTimeString' description: When the report was requested. readyAt: type: string allOf: - $ref: '#/components/schemas/dateTimeString' nullable: true description: When the file became available. `null` until `READY`. description: >- A report of your organization: a statement, a balance certificate or a bank confirmation letter. example: object: report reportId: rpt_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 type: ACCOUNT_STATEMENT format: PDF status: READY from: '2026-09-01' to: '2026-09-30' asOf: null currency: USD fileName: NXOS - Account statement - 2026-09 - Acme Ltd.pdf sizeBytes: 48211 createdAt: '2026-10-01T09:12:44.000Z' readyAt: '2026-10-01T09:12:51.000Z' Error400: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. Error401: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: missing_api_key message: 'Missing or invalid Authorization header. Expected: Bearer ' requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error403: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. Error404: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. Error409: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. Error422: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. Error429: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: rate_limited message: 'Rate limit exceeded: 1000 requests per minute. Retry in 23 seconds.' requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 Error500: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorBody' description: Standard error response returned by all endpoints on failure. example: error: code: internal_error message: An unexpected error occurred. requestId: req_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 CreateStatementRequest: type: object required: - type - format - from - to properties: type: type: string enum: - ACCOUNT_STATEMENT - TRANSACTION_STATEMENT description: '`ACCOUNT_STATEMENT` or `TRANSACTION_STATEMENT`.' format: allOf: - $ref: '#/components/schemas/ReportFormat' description: File format. from: type: string description: First day covered (`YYYY-MM-DD`, UTC). No earlier than 2024-01-01. to: type: string description: >- Last day covered, inclusive (`YYYY-MM-DD`, UTC). At most 366 days after `from`; a range reaching today runs up to now. currency: type: string nullable: true description: >- Asset code of the one currency to cover. Omit or pass `null` for every currency. description: Request an account or transaction statement over a range of days. example: type: ACCOUNT_STATEMENT format: PDF from: '2026-09-01' to: '2026-09-30' currency: USD CreateBalanceCertificateRequest: type: object required: - type - asOf properties: type: type: string enum: - BALANCE_CERTIFICATE description: Always `BALANCE_CERTIFICATE`. asOf: type: string description: >- The day whose closing balances to certify (`YYYY-MM-DD`, UTC). Must have ended. currency: type: string nullable: true description: >- Asset code of the one currency to cover. Omit or pass `null` for every currency. description: Request a balance certificate at the end of a past day. Always a PDF. example: type: BALANCE_CERTIFICATE asOf: '2026-09-30' currency: null CreateBankConfirmationLetterRequest: type: object required: - type - fundingMethodId - asset properties: type: type: string enum: - BANK_CONFIRMATION_LETTER description: Always `BANK_CONFIRMATION_LETTER`. fundingMethodId: type: string description: The `BANK` funding method whose account to confirm. asset: type: string description: >- Asset code of the account to confirm. Must be enabled on the funding method. description: >- Request a letter confirming the bank account one of your funding methods receives on. Always a PDF. Available once your organization is approved, for a `BANK` funding method with the asset enabled. example: type: BANK_CONFIRMATION_LETTER fundingMethodId: funding_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 asset: EUR ReportType: type: string enum: - ACCOUNT_STATEMENT - TRANSACTION_STATEMENT - BALANCE_CERTIFICATE - BANK_CONFIRMATION_LETTER description: The kind of document a report is. ReportFormat: type: string enum: - PDF - CSV description: File format of a report. ReportStatus: type: string enum: - PENDING - PROCESSING - READY - FAILED description: |- Where a report stands. - `PENDING` / `PROCESSING` — being generated, usually within seconds. - `READY` — the file can be downloaded. - `FAILED` — the report could not be generated. Request it again. dateTimeString: type: string description: ISO 8601 timestamp string. ErrorBody: type: object required: - code - message - requestId properties: code: allOf: - $ref: '#/components/schemas/ErrorCode' description: Machine-readable error code. message: type: string description: Human-readable error message. requestId: type: string description: Unique identifier for this request, useful for debugging. ErrorCode: type: string enum: - missing_api_key - authentication_failed - invalid_api_key - forbidden - acting_org_not_found - authorization_required - swap_direction_not_allowed - sub_org_tier_not_available - service_not_enabled - not_found - organization_not_found - account_not_found - quote_not_found - beneficiary_not_found - transaction_not_found - funding_method_not_found - authorization_not_found - nxosnet_handle_not_found - sub_org_tier_not_found - report_not_found - quote_expired - quote_already_used - beneficiary_already_archived - beneficiary_not_archived - beneficiary_blocked - transaction_blocked - transaction_not_held - fee_schedule_drifted - nxosnet_not_enabled - nxosnet_handle_taken - chain_send_failed - swift_copy_not_found - swift_copy_not_ready - bank_unavailable - idempotency_key_in_use - idempotency_request_in_flight - referral_invite_already_accepted - report_not_ready - too_many_pending_reports - invalid_request - insufficient_funds - trade_size_out_of_bounds - validation_error - invalid_document - too_many_documents - document_too_large - document_not_found - document_not_uploaded - share_token_invalid - verification_import_unsupported - verification_required - rate_limited - webhooks_unavailable - internal_error description: All possible error codes returned by the API. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.