# List e-invoices > The einvoices.list operation: GET /api/v1/einvoices in the REST API and the einvoices_list tool in the MCP server. Lists the brand's e-invoices in the mode of the request, newest first: one per invoice or credit note whose case (the buyer's country and transaction type) the entity's e-invoicing settings route to a provider, with its status (`pending`, `queued`, `delivered`, `accepted`, `rejected`, `failed`), the provider's ID and the stored document. Filter by `documentId` (an invoice's or credit note's e-invoice) or `status`. Paginate with `limit` (1–100, default 10) and `starting_after`. ## At a glance - **REST:** `GET /api/v1/einvoices` - **MCP tool:** `einvoices_list` - **Operation ID:** `einvoices.list` - **Scope:** Brand - **Permission:** `invoices:read` - **Risk tier:** `read` - **Dry run:** Not supported - **Idempotency:** Not needed (read only) - **Modes:** Test and live - **Pagination:** `limit` (at most 100) and `starting_after` - **Authentication:** API key with the `invoices:read` scope - **Since:** M13 ## Request ### Query parameters | Field | Type | Required | Description | | ---------------- | ------------------------------------------------------------------------- | -------- | --------------------------------------------------------------- | | `documentId` | string | No | The e-invoice of one invoice (`inv_…`) or credit note (`cn_…`). | | `status` | one of `pending`, `queued`, `delivered`, `accepted`, `rejected`, `failed` | No | Only e-invoices in this status. | | `limit` | integer (1 to 100) | No | Page size, 1 to 100 (default 10). | | `starting_after` | `einv_…` ID | No | The `next_cursor` of the previous page. | ## Response `200 OK` with a JSON object, a page of the list (newest first): | Field | Type | Description | | ------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | `"list"` | | | `data` | array of object | | | `data[].id` | `einv_…` ID | | | `data[].object` | `"einvoice"` | | | `data[].livemode` | boolean | | | `data[].orgId` | `org_…` ID | | | `data[].entityId` | `ent_…` ID | | | `data[].brandId` | `brd_…` ID | | | `data[].documentKind` | one of `invoice`, `credit_note` | | | `data[].documentId` | string | The invoice (`inv_…`) or credit note (`cn_…`) it was generated from. | | `data[].documentNumber` | string | | | `data[].customerId` | string or null | | | `data[].country` | string | | | `data[].transactionType` | one of `b2b`, `b2g`, `b2c` | | | `data[].provider` | string | | | `data[].format` | one of `UBL_2_1_PEPPOL_BIS_3`, `CII`, `national` | | | `data[].status` | one of `pending`, `queued`, `delivered`, `accepted`, `rejected`, `failed` | `pending` (queued for sending), `queued` (the provider took it), `delivered`, `accepted`, `rejected` (by the receiver) or `failed` (couldn't be generated or sent). | | `data[].externalId` | string or null | The provider's ID of the transmission. | | `data[].buyerEndpoint` | string or null | | | `data[].sellerEndpoint` | string or null | | | `data[].buyerReference` | string or null | | | `data[].file` | object or null | The generated document as stored (UBL XML) and the generator version that wrote it. | | `data[].error` | object or null | | | `data[].attempts` | integer | | | `data[].sentAt` | date-time or null | | | `data[].lastCheckedAt` | date-time or null | | | `data[].history` | array of object | | | `data[].history[].status` | one of `pending`, `queued`, `delivered`, `accepted`, `rejected`, `failed` | | | `data[].history[].at` | date-time | | | `data[].history[].reason` | string or null | | | `data[].createdAt` | date-time | | | `data[].updatedAt` | date-time | | | `has_more` | boolean | | | `next_cursor` | `einv_…` ID or null | | ## Examples ### The e-invoice of an invoice ```http GET /api/v1/einvoices?documentId=inv_01jacq4m3xf0v8w9zq2y7k5n70 Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "einv_01jbxa6qk3f0v8w9zq2y7k5n70", "object": "einvoice", "livemode": false, "orgId": "org_01jacq4m3xf0v8w9zq2y7k5n6a", "entityId": "ent_01jacq4m3xf0v8w9zq2y7k5n6h", "brandId": "brd_01jacq4m3xf0v8w9zq2y7k5n6j", "documentKind": "invoice", "documentId": "inv_01jacq4m3xf0v8w9zq2y7k5n70", "documentNumber": "ACME-2026-000101", "customerId": "cus_01jacq4m3xf0v8w9zq2y7k5n6k", "country": "HR", "transactionType": "b2b", "provider": "fake", "format": "UBL_2_1_PEPPOL_BIS_3", "status": "accepted", "externalId": "fake_einv_000001_inv_01jacq4m3xf0v8w9zq2y7k5n70", "buyerEndpoint": null, "sellerEndpoint": null, "buyerReference": null, "file": { "fileId": "file_01jbxa6qk3f0v8w9zq2y7k5n71", "sha256": "3f0c1e9b7a2d4c6e8f0a1b3c5d7e9f1a2b4c6d8e0f1a3b5c7d9e1f2a4b6c8d0e", "size": 4211, "generator": "ubl_peppol_bis_3@1" }, "error": null, "attempts": 1, "sentAt": "2026-10-14T09:31:02.000Z", "lastCheckedAt": "2026-10-14T09:45:00.000Z", "history": [ { "status": "pending", "at": "2026-10-14T09:30:05.000Z", "reason": null }, { "status": "queued", "at": "2026-10-14T09:31:02.000Z", "reason": null }, { "status": "accepted", "at": "2026-10-14T09:45:00.000Z", "reason": null } ], "createdAt": "2026-10-14T09:30:05.000Z", "updatedAt": "2026-10-14T09:45:00.000Z" } ], "has_more": false, "next_cursor": null } ``` ## Errors | Code | HTTP status | When | What to do | | -------------------------------------------------------------------------------------- | ----------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | | [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed) | 400 | A filter is malformed. | Fix the fields listed in `details.issues` and send the request again. | | [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required) | 400 | The request names no brand. | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't see this brand's invoices. | Ask an organization owner or admin for a role or scope that allows this action. | It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).