---
title: "Documents API"
canonical: https://documentation.maventa.com/api-specification/rest-api/documents-api/
---

The Documents API handles business documents beyond standard invoices and credit notes such as orders and other structured business files. Use it to send and download documents, track their delivery events, and manage associated files. For details on document handling see the [document exchange guide](https://documentation.maventa.com/integration-guide/peppol/document-exchange/)

For invoice-specific operations, use the [Invoices API](https://documentation.maventa.com/api-specification/rest-api/invoices-api/) instead.

## API endpoints

### GET /v1/documents

Query documents

#### Pagination and sorting
The items per page parameter **per_page** will default to 10 if not provided, also the **page** parameter will default to 1 if not provided.
The maximum value of the **per_page** parameter is 100.
Default order of the items is descending by the created_at attribute.
Additional information about returned page can be extracted from the returned header parameters:
 - **X-Total**: Total number of items
- **X-Total-Pages**: Total number of pages
- **X-Page**: Index of the current page
- **X-Next-Page**: Index of the next page
- **X-Prev-Page**: Index of the previous page
- **X-Per-Page**: Items per page
- **Link**: Links to the first, previous, next, and last pages can be found from this header
The page indexing starts from 1.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| ids | query | array[string] | no | Batch of document IDs. Maximum of 100 per query |
| direction | query | string | no | Received or sent documents |
| type | query | array[string] | no | List of document types.                                                     Possible values: UNKNOWN, INVOICE, CREDIT_NOTE, ORDER, ORDER_RESPONSE, CATALOGUE, CATALOGUE_RESPONSE, SELF_BILLING_INVOICE, DESPATCH_ADVICE, RECEIPT, VOUCHER, BANK_FILE, REMINDER, SCAN, INVOICE_RESPONSE, MESSAGE_LEVEL_RESPONSE, EXPRESSION_OF_INTEREST_REQUEST, EXPRESSION_OF_INTEREST_RESPONSE, TENDER_STATUS_REQUEST, CALL_FOR_TENDERS, TENDER, TENDER_RECEIPT, ORDER_CHANGE, ORDER_CANCELLATION, SELF_BILLING_CREDIT_NOTE |
| status | query | array[string] | no | List of document states.                                                     Possible values: PROCESSING, DELIVERED, CONFIRMED_DELIVERY, FAILED |
| created_at_start | query | string | no | Creation time |
| created_at_end | query | string | no | Creation time |
| number | query | string | no | Document number |
| reference | query | string | no | Document reference |
| query | query | string | no | Query Documents on multiple fields. (Exact matches on id, reference and number) |
| sort | query | array[string] | no | List of fields used for sorting.   Ascending by default, include "-" before the field name to reverse the order (descending).   Supported values: **id, type, status, number, reference, created_at, received_at**   E.g. [-created_at, number] |
| page | query | integer | no | Page to fetch |
| per_page | query | integer | no | Number of items per page, values up to 100 supported |
| fields | query | array[string] | no | Fields to return in response |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Query documents | `array[API_Entities_Document]` |

### POST /v1/documents


Create document

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| file | formData | file | no | File content as a single file |
| files[n][file] | formData | file | no | File content as one of multiple |
| files[n][file_type] | formData | string | no | File type |
| references[n][reference_id] | formData | string | no | Reference to use for the document |
| references[n][reference_id_type] | formData | string | no | Type of reference id |
| references[n][checksum] | formData | string | no | Checksum of the referenced content |
| references[n][file_type] | formData | string | no | File type |
| type | formData | string | no | Type of Document |
| transmission_id | formData | string | no | Unique transmission ID |
| transmission_at | formData | string | no | Official transmission timestamp |
| external_id | formData | string | no | External identifier linked to the document |
| recipient_name | formData | string | no | Name of Recipient |
| recipient_country | formData | string | no | Recipient country in ISO 3166-1 alpha-2 format (2 letters) |
| recipient_eia | formData | string | no | Electronic Invoicing Address of the recipient |
| recipient_operator | formData | string | no | Operator of Recipient |
| sender_name | formData | string | no | Name of Sender |
| sender_country | formData | string | no | Sender country in ISO 3166-1 alpha-2 format (2 letters) |
| sender_eia | formData | string | no | Electronic Invoicing Address of the sender |
| fields | query | array[string] | no | Fields to return in response |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | Create document | `API_Entities_Document` |
| 422 | - **document_duplicate_transmission_id**: The provided transmission_id is already in use | `API_Entities_Error` |

### GET /v1/documents/{id}


Document details

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | ID of Document |
| return_format | query | array[string] | no | Content type for the details. Will return the stored metadata as default. |
| fields | query | array[string] | no | Fields to return in response |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Document details | `API_Entities_Document` |

### PATCH /v1/documents/{id}


Update existing document

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | ID of Document |
| fields | query | array[string] | no | Fields to return in response |

**Request body**

Schema: `patchV1DocumentsId`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| status | `string` | no | Change the state of the document.                                       Possible values: CONFIRMED_DELIVERY |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Document updated sucessfully |  |
| 409 | - **document_in_invalid_state**: Document must be in the delivered state | `API_Entities_Error` |

### GET /v1/documents/{id}/events


Document's events

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | ID of Document |
| fields | query | array[string] | no | Fields to return in response |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Document's events | `API_Entities_DocumentEvent` |

### GET /v1/files


List document files

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| document_id | query | string | yes | ID of Document |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | List document files | `API_Entities_DocumentFileInDocument` |

### GET /v1/files/{id}


Get file content

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | ID of DocumentFile |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Get file content |  |


_OpenAPI spec snapshot: 2026-05-06_