---
title: "Invoices API"
canonical: https://documentation.maventa.com/api-specification/rest-api/invoices-api/
---

The Invoices API covers both sending and receiving invoices through Maventa. Use it to send invoices for delivery, download received invoices and their files, track status and events, and handle rerouting when a delivery attempt fails.

For a full walkthrough of the sending process, including recipient lookup, routing, and format selection, see the [invoice sending integration guide](https://documentation.maventa.com/integration-guide/invoice-sending/invoice-sending/). For details on receiving see the [invoice receiving integration guide](https://documentation.maventa.com/integration-guide/invoice-receiving/).

## API endpoints

### GET /v1/invoices

List invoices

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| direction | query | string | no | Received or sent invoices |
| status | query | array[string] | no | Invoice status |
| ids | query | array[string] | no | Batch of invoice IDs. Maximum of 100 per query |
| number | query | string | no | Invoice number |
| reference | query | string | no | Invoice reference |
| received_at_start | query | string | no | Received at start timestamp |
| received_at_end | query | string | no | Received at end timestamp |
| created_at_start | query | string | no | Created at start timestamp |
| created_at_end | query | string | no | Created at end timestamp |
| 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: **received_at**                               E.g. -received_at |
| page | query | integer | no | Page to fetch |
| per_page | query | integer | no | Number of items per page, values up to 100 supported |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | List invoices | `array[Invoices_HttpApi_Entities_Invoice]` |

### POST /v1/invoices

Upload new invoice

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| file | formData | file | yes | File content. Please make sure to provide the "filename" Content-Disposition header field as well as specified in the rfc2183. |
| format | formData | string | no | File format |
| recipient_type | formData | string | no | Only in Norway, set to "consumer" to use route_order |
| recipient_eia | formData | string | no | Recipient EIA |
| recipient_email | formData | string | no | Recipient email address |
| recipient_operator | formData | string | no | Recipient operator |
| disabled_routes | formData | array[string] | no | Routes to explicitly disable |
| sender_comment | formData | string | no | Text that will be added in the email message if invoice is delivered by email |
| uuid | formData | string | no | Unique invoice uuid, generated automatically if not specified. |
| lang | formData | string | no | Set language of PDF generated by us and email what recipient receives. |
| route_order | formData | array[string] | no | Consumer routes to use. Leave empty to use default. Note! 'netbank_cvl' and 'netbank_cvl_hold' are deprecated since 05/2022. |
| recipient_phone_number | formData | string | no | Recipient phone number in international format. Used in Yes2All lookups. |
| recipient_date_of_birth | formData | string | no | Recipient date of birth in YYYY-MM-DD format. Used in Yes2All lookups. |
| recipient_ssn | formData | string | no | Recipient social security number. Used in Yes2All lookups. |
| recipient_efaktura_id | formData | string | no | Recipient unique eFaktura ID |
| b2cno_document_type | formData | string | no | B2C document type for special documents |
| payment_instruction_identifier | formData | string | no | PaymentInstructionIdentifier, used in Finnish B2C invoicing only. |
| print_settings[color] | formData | boolean | no | Enable color printing |
| print_settings[letter_class] | formData | string | no | Letter class |
| print_settings[prevent_digital_post] | formData | boolean | no | Prevent invoice from being sent to OmaPosti (Finland only) |
| print_settings[print_own_image] | formData | boolean | no | Use own image when printing (overrides company settings) |
| print_settings[allow_kivra_fi] | formData | boolean | no | Try Kivra FI before printing even if "einvoice" route is disabled in disabled_routes parameter. Only applies for B2C invoices. |
| prevent_routing | formData | boolean | no | Prevent routing of the invoice. Invoice will be set to SENT state without actually sending it anywhere. Intended use is for creating assignments without sending an invoice for the collection services |
| email_settings[xml_format] | formData | string | no | Forces the invoice to be sent via email and includes the XML attachment in the specified format |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 201 | Upload new invoice | `Invoices_HttpApi_Entities_Invoice` |

### GET /v1/invoices/{id}

Invoice details

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Invoice ID |
| return_format | query | string | no | Desired format |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Invoice details | `Invoices_HttpApi_Entities_Invoice` |

### GET /v1/invoices/{id}/actions

List invoice actions

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Invoice ID |
| type | query | array[string] | no | Action type |
| channel_details_version | query | integer | no | Version for channel_details |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | List invoice actions | `array[Invoices_HttpApi_Entities_InvoiceAction]` |

### PATCH /v1/invoices/{id}/invoice_events

Change state for recevied events

**Parameters**

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

**Request body**

Schema: `patchV1InvoicesIdInvoiceEvents`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| state | `string` | yes | State to change to |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 |  |  |

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

Fetch file content

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Invoice ID |
| file_id | path | string | yes | Invoice file ID |

**Responses**

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

### PUT /v1/invoices/{id}/reroute/einvoice


Reroutes invoice via einvoice

**Parameters**

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

**Request body**

Schema: `putV1InvoicesIdRerouteEinvoice`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| recipient_eia | `string` | yes | Recipient electronic invoice address |
| recipient_operator | `string` | yes | Recipient operator |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Reroutes invoice via einvoice |  |

### PUT /v1/invoices/{id}/reroute/email


Reroutes invoice via email

**Parameters**

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

**Request body**

Schema: `putV1InvoicesIdRerouteEmail`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| recipient_email | `string` | yes | Recipient email address |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Reroutes invoice via email |  |

### PUT /v1/invoices/{id}/reroute/print


Reroutes invoice via print

**Parameters**

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

**Request body**

Schema: `putV1InvoicesIdReroutePrint`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| recipient_name | `string` | yes | Recipient name |
| recipient_address1 | `string` | yes | Recipient address line 1 |
| recipient_address2 | `string` | no | Recipient address line 2 |
| recipient_post_code | `string` | yes | Recipient post code |
| recipient_post_office | `string` | yes | Recipient post office |
| recipient_state | `string` | no | Recipient state |
| recipient_country | `string` | yes | Recipient country in ISO 3166-1 alpha-2 format (2 letters) |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Reroutes invoice via print |  |

### GET /v1/invoices/{id}/reports


Fetch user reports for invoice

**Parameters**

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

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Fetch successfully completed | `array[UserReport]` |
| 400 | Bad Request | `API_Entities_Error` |
| 401 | Unauthorized | `API_Entities_Error` |
| 403 | Forbidden | `API_Entities_Error` |
| 404 | No user report found | `API_Entities_Error` |

### POST /v1/invoices/{id}/reports


Report sender of fraud attempt

**Parameters**

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

**Request body**

Schema: `postV1InvoicesIdReports`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| reason | `array[string]` | yes | Reporting reason. Can be multiple. |
| contact_email | `string` | yes | Contact email for reporter in case of follow up questions |
| description | `string` | no | Description for reporting with certain reasons |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | Company successfully reported |  |
| 400 | Bad Request | `API_Entities_Error` |
| 401 | Unauthorized | `API_Entities_Error` |
| 403 | Forbidden | `API_Entities_Error` |
| 409 | Conflict: company already reported | `API_Entities_Error` |

### DELETE /v1/invoices/{id}/reports/{report_id}


Delete user report for invoice

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | yes | Invoice ID |
| report_id | path | string | yes | Report ID |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 204 | User report successfully deleted |  |
| 400 | Bad Request | `API_Entities_Error` |
| 401 | Unauthorized | `API_Entities_Error` |
| 403 | Forbidden | `API_Entities_Error` |
| 404 | No user report found | `API_Entities_Error` |

### POST /v1/invoices/{id}/responses/nemhandel


Sets the business response for an invoice in the Nemhandel network. When an invoice has a final response you cannot set another response. The responses have to be set in a predefined order, specified by the standards.Note: This API has a vendor lock. To enable access, please contact Maventa Support before using this endpoint.

**Parameters**

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

**Request body**

Schema: `postV1InvoicesIdResponsesNemhandel`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| response | `string` | yes | Invoice response type |
| reason | `string` | no | Reason for response, required for some responses |

**Responses**

| Status | Description | Schema |
| --- | --- | --- |
| 200 | Return | `Invoices_HttpApi_Entities_InvoiceResponseNemhandel` |
| 400 | Bad request |  |
| 404 | Invoice not found |  |
| 503 | Service unavailable. Try again later. |  |


_OpenAPI spec snapshot: 2026-05-06_