---
title: "Invoice receiving"
canonical: https://documentation.maventa.com/integration-guide/invoice-receiving/
---

Maventa makes it easy to receive invoices from multiple sources, including country-specific e-invoicing networks, Peppol, and PDF scanning services. Once activated, Maventa registers your company in the relevant electronic address directories and assigns you an electronic invoice address (EIA) that senders can use to deliver invoices directly to you.

All invoices first arrive in your Maventa account, where they can be downloaded or fetched via API into your system. You can also use webhooks to create a smooth, automated receiving flow and integrate the [Detect](https://documentation.maventa.com/integration-guide/invoice-receiving/detect/) service for validation and fraud detection. For extra protection, the fraud reporting feature allows you to flag suspicious senders and help prevent invoice fraud across the network.

> [!NOTE]
> This guide covers the REST API. If you are using the SOAP API, see the [SOAP invoice receiving API methods](https://documentation.maventa.com/api-specification/soap-api/invoice-receiving-api-methods/) instead. For authentication setup, see [Getting started with the REST API](https://documentation.maventa.com/api-specification/rest-api/getting-started/).

## Typical receiving flow

The following steps describe the recommended flow for receiving invoices:

1. **Activate** — Enable VISMA Network and Peppol receiving for the company.
2. **Listen** — Register a webhook for `DOCUMENTS.INVOICE.RECEIVED` events.
3. **Download** — When a webhook fires, fetch the invoice XML, image, and attachments by ID.
4. **Validate** — If Detect is enabled, fetch fraud and validation check results.
5. **Back up** — Poll `GET /v1/invoices` once a day to catch any invoices missed by webhooks.

Received invoices are fetched from the company's Maventa account into your system. Maventa does not provide an approval workflow — approval, cost allocation, and coding to projects or accounts happen in your system. Fetching an invoice does not remove it from Maventa or hide it from other integrations connected to the same company, and Maventa does not track which invoices have been approved.

If several systems are involved — for example, one for approval and another for bookkeeping — let one system fetch the invoices from Maventa and pass the approved invoices on to the next. This avoids duplicate processing and duplicate receive charges. See [several integrations for one company](https://documentation.maventa.com/integration-guide/account-management/companies-and-settings/#several-integrations-for-one-company).

### Prerequisites

To start receiving invoices, make sure you have:

* **Company account enabled for receiving**: Your company must have an active Maventa account with invoice receiving enabled.
* **Invoice XML handling capabilities**: During download, you select which XML format to use. Maventa supports a variety of international and national formats. See the full list of [supported formats](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Validator+API) and more information about [invoicing formats](https://documentation.maventa.com/integration-guide/invoicing-formats/invoicing-formats/).

## Step 1: Activate invoice receiving

To start receiving invoices, enable the VISMA Network setting. This is the main control for receiving e-invoices in Maventa. It allows the company to receive invoices from other Maventa users and, depending on the country, also from other operators or banks.

Once VISMA Network is turned on, additional networks such as Peppol or scanning can be enabled separately. Maventa recommends enabling Peppol for all customers to ensure the widest possible reach for receiving invoices.

After activation, the company is automatically registered in the relevant electronic address directories (depending on the country) and assigned an electronic invoice address (EIA) that senders can use to deliver invoices directly. The company also becomes visible as an invoice recipient in Maventa Finder and via the [lookup method](https://documentation.maventa.com/integration-guide/invoice-sending/invoice-sending/#manual-lookup).

You can check which address registries are used in each country, as well as whether the country supports operator or bank networks, in the [country-specific guides](https://documentation.maventa.com/services-and-reach/overview/). Typically, receiving is activated at the same time the account is registered, but it can also be enabled later if needed.

### Activate VISMA Network

Call the [POST /v1​/company​/profiles](#operations-company-postV1CompanyProfiles) endpoint authenticated with `company` scope, providing the network `VISMA` and profiles `INVOICE_AND_CREDIT_NOTE`:

```json
{
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "network": "VISMA"
}
```

No other parameters are needed. Expect the `status` field in the response to be `pending`. To confirm successful registration, call the [GET /v1​/company​/profiles](#operations-company-getV1CompanyProfiles) endpoint and check that the status has changed to `active`.

### Register company as Peppol receiver

When activating the electronic receiving setting, Maventa recommends that all customers are also registered to receive electronic invoices in the international [Peppol network](https://documentation.maventa.com/integration-guide/peppol/peppol-network/). When a company is registered, its information is added to the [Peppol Directory](https://directory.peppol.eu/public).

Authenticate with `company` scope and call [POST /v1​/company​/profiles](#operations-company-postV1CompanyProfiles), specifying the network as `PEPPOL` and profiles `INVOICE_AND_CREDIT_NOTE`:

```json
{
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "network": "PEPPOL"
}
```

The profile `INVOICE_AND_CREDIT_NOTE` automatically registers both document types for Peppol BIS Billing 3.0. Some countries also include additional, country-specific profiles automatically. Maventa automatically keeps the Peppol registration updated as new invoice profiles are introduced. There is no need to register new profiles when the format updates.

<details>
<summary>Peppol BIS Billing UBL Invoice V3</summary>

**Peppol document identifier:**

- `urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**Process identifier:** `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing UBL Credit Note V3</summary>

**Peppol document identifier:**

- `urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**Process identifier:** `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

Call [GET /v1​/company​/profiles](#operations-company-getV1CompanyProfiles) again to verify that the status of the `PEPPOL` network registration is active. The error code `PROFILE_ALREADY_REGISTERED` means the profile is already registered — either because the company is registered with another Peppol access point, or because the profile was already registered for the company through Maventa and was included in the request again. The request is processed as a single operation, so if any profile in the array is already registered, the whole request fails and none of the new profiles are added. When adding profiles to a company that already receives invoices, send only the profiles that are not yet registered.

> [!WARNING]
> Switching Peppol access points requires coordination with the current provider. If the company is registered with another access point, contact them and ask them to deregister the company. Once deregistered, repeat the registration call above. The process typically takes a few business days.

With registration, the company is visible with an electronic invoicing address (EIA) to suppliers in the Peppol network.

The [Peppol Directory](https://directory.peppol.eu/public) is available as a reference tool for looking up registered companies. Maventa automatically updates this directory, making your company visible there. Note that the Peppol Directory is not part of the actual delivery infrastructure — it serves informational purposes only.

### Deactivate invoice receiving

To stop receiving invoices on a specific network, delete the corresponding network registration. This removes the company from the associated electronic address directories, and senders can no longer deliver invoices to the company through that network.

First, retrieve the profile ID by calling [GET /v1​/company​/profiles](#operations-company-getV1CompanyProfiles) with `company` scope. Filter by network if needed — for example, `?network=VISMA` or `?network=PEPPOL`. The response includes the `id` for each active registration.

Then, call [DELETE /v1​/company​/profiles/{id}](#operations-company-deleteV1CompanyProfilesId) with the profile `id` to delete the registration.

> [!WARNING]
> The VISMA Network registration cannot be deleted while Peppol or scanning registrations are still active. Deactivate those registrations first before removing the VISMA Network profile.

> [!NOTE]
> Not all profiles can be deleted. If deletion is not allowed for a specific profile, the endpoint returns a `409 Conflict` response.

To deregister from Peppol specifically, use the same approach: find the Peppol profile ID from the list and delete it. The company is then removed from the Peppol network and the [Peppol Directory](https://directory.peppol.eu/public). Senders looking up the company through Peppol will no longer find a registered e-invoicing address.

Each network registration can be deactivated independently. For example, deleting the Peppol registration does not affect the VISMA Network registration, and vice versa.

#### Receiving invoice extensions

To enable receiving of invoice extensions, call [PUT /v1/company/profiles/{id}/extensions](https://swagger.maventa.com/#/company/putV1CompanyProfilesIdExtensions).

Example request:

```json
{
  "profile_name": "INVOICE_AND_CREDIT_NOTE",
  "extensions": ["GACCOUNT10"]
}
```

Currently, Maventa supports only the GACCOUNT10 extension for the Netherlands.

To view the active extensions, call [GET /v1/company/profiles/{id}](https://swagger.maventa.com/#/company/getV1CompanyProfilesId).

```json
{
  // ...
  "profiles_with_extensions": [
    {
      "profile_name": "INVOICE_AND_CREDIT_NOTE",
      "extensions": ["GACCOUNT10"]
    }
  ]
}
```

To disable receiving of invoice extensions, call [PUT /v1/company/profiles/{id}/extensions](https://swagger.maventa.com/#/company/putV1CompanyProfilesIdExtensions) with an empty extensions array:

```json
{
  "profile_name": "INVOICE_AND_CREDIT_NOTE",
  "extensions": []
}
```

## Step 2: Fetch received invoices

To determine when an invoice has been received to a company account, you can either listen for webhook notifications or poll the API for incoming invoices. Webhooks are the preferred method, as they provide faster and more efficient delivery compared to regular polling.

### Webhooks

Webhooks notify your system immediately when a new invoice arrives, enabling a seamless automated receiving flow. As a backup routine, Maventa recommends polling for invoices once a day.

#### Register for webhook notifications for received invoices

Register for invoice receipt events by calling [POST /v1/company/notifications](#operations-company-postV1CompanyNotifications).

Example registering for RECEIVED events for invoices:

### Request

```json
{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.RECEIVED"
  ]
}
```

### Response

```json
{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.RECEIVED"
  ]
}
```

Maventa calls the specified endpoint with a payload like this:

```json
{
  "event":            "DOCUMENTS.INVOICE.RECEIVED",
  "company_id":       "53a4e05d-42f0-4e76-acd6-968ab4558c6f",
  "event_timestamp":  "2024-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":     "c154feee-399b-488e-aecd-580578b140e0",
    "invoice_number": "1002",
    "origin":         "PEPPOL",
    "sender_name":    "Sender",
    "sender_bid":     "937729111"
  }
}
```

Example registering for RECEIVED events for invoices with vendor webhooks:

### Request

```json
{
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "vendor_key": "your_vendor_api_key_here",
  "events": [
    "DOCUMENTS.INVOICE.RECEIVED"
  ]
}
```

### Response

```json
{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.RECEIVED"
  ]
}
```

Store the `event_data.invoice_id` for later processing and deduplication. Maventa may deliver the same webhook event more than once (for example, if your endpoint is temporarily unreachable), so always check whether an invoice ID has already been processed before downloading it again.

Your endpoint should return an HTTP `200` status code to acknowledge receipt. If Maventa does not receive a `200` response, the webhook is retried. Refer to the [Webhooks guide](https://documentation.maventa.com/integration-guide/integration-tools/webhooks/) for full details on retry behaviour, payload signatures, and configuration.

### Polling

If you do not use webhooks, you can poll the API to list new invoices and then download them with their attachments. Maventa recommends polling no more than once or twice per day. Even when using webhooks, poll once a day as a backup to catch any missed deliveries.

#### List new received invoices

Use [GET /v1/invoices](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/getV1Invoices) with parameters `direction=RECEIVED`, `received_at_start`, and `received_at_end` to get a list of invoices to download. This method is called per company, so it is only possible to list invoices from one company at a time.

The timestamp parameters use ISO 8601 format, for example:

```http
GET /v1/invoices?direction=RECEIVED&received_at_start=2025-01-15T08:00:00%2B02:00&received_at_end=2025-01-15T20:00:00%2B02:00
```

The response is paginated. Use the `page` and `per_page` parameters to iterate through results. Check the response headers or result count to determine whether more pages are available.

You can control the ordering with the `sort` parameter: use `received_at` for oldest first, or `-received_at` for newest first. Newest first is the default for received invoices.

> [!NOTE]
> * Call the method starting with the latest fetch timestamp and ending with the current timestamp.
> * If the API returns an error, do not update the stored timestamp. Retry the listing later.
> * Save the returned invoice IDs locally with a status such as "pending download".
> * The server timestamp is GMT+2. Differences between client-side and server-side clocks can create gaps. Add a buffer of about 1 minute before and after the timestamps to avoid missing invoices.

### Download invoice based on ID

After you have saved the new incoming invoice IDs, download the invoice files and attachments into your system.

Invoice downloading involves obtaining:

* Invoice metadata
* Invoice data
* Invoice attachments

Use [GET /v1/invoices/{id}](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/getV1InvoicesId) to download the invoice XML file in the specified format, or to download the invoice image. Set the `return_format` parameter to the desired format.

Common `return_format` values for XML download:

| Value | Format |
|-------|--------|
| `PEPPOLBIS30` | Peppol BIS Billing 3.0 (recommended) |
| `FINVOICE30` | Finvoice 3.0 |
| `TEAPPSXML30` | TEAPPSXML 3.0 |
| `UBL20` | UBL 2.0 |
| `SIUBL` | Visma SI-UBL |

For the full list of supported formats, see the [Validator API specification](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Validator+API) and the [invoicing formats](https://documentation.maventa.com/integration-guide/invoicing-formats/invoicing-formats/) page.

> [!NOTE]
> * Mark an invoice as successfully retrieved only after it has actually been downloaded. If the download fails, log the error and retry later.
> * Use the locally stored invoice ID list to ensure the same invoice is not downloaded twice.

> [!NOTE]
> Each received invoice is billed once per vendor API key, and the charge is triggered when you fetch the invoice's content. Re-fetching or re-downloading the same invoice with the same vendor API key does not add another charge. Fetching the same invoice with a different vendor API key counts as a separate receive and creates a new billing action.

#### Download invoice image and attachments

To download the invoice image, use the `return_format` parameter:

* `ORIGINAL_OR_GENERATED_IMAGE` — returns the original image if one exists, otherwise Maventa generates one
* `ORIGINAL_IMAGE` — returns an image only if the original exists
* `GENERATED_IMAGE` — returns an image generated by Maventa

##### Example: Original format Peppol BIS3

If the invoice's original format is Peppol BIS3 and you download it as Peppol BIS3, you only need the XML file as it has all original attachments embedded.

> [!WARNING]
> When downloading in a different format than the original, Maventa converts the XML but does not embed separate attachments into the converted file. Download attachments separately using the files endpoint described below.

##### Example: Original format TEAPPSXML 3.0 downloaded as Finvoice 3.0

If the invoice's original format is TEAPPSXML 3.0 and it includes an invoice image and extra attachments:

* Download the invoice as Finvoice 3.0 with [GET /v1/invoices/{id}](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/getV1InvoicesId) by setting `return_format` to `FINVOICE30`.
* Then download the invoice image or other attachments using the same endpoint with `return_format` set to one of the image options described above.

Invoices may also contain attachments, listed in the `files` array of the invoice metadata. Download each attachment separately using [GET /v1/invoices/{id}/files/{file_id}](#operations-invoices-getV1InvoicesIdFilesFileId) with the `id` from each file entry.

Most often, attachments include an invoice image — a PDF document with a visual representation of the invoice data. If one is not provided by the sender, Maventa generates it.

#### Invoice origin and origin_type details

In the invoice details, the `origin` field indicates the source of the received invoice — for example, `PEPPOL`, `VISMA`, or `SCAN`. If the `origin` is `SCAN`, the `origin_type` field provides additional detail about the scanning method:

| `origin_type` | Description |
|----------------|-------------|
| `SCAN_PDF` | Scanned from a PDF file |
| `SCAN_PAPER` | Scanned from a paper invoice |
| `AUTOSCAN` | Automatically scanned from a PDF file (ML-based) |
| `SCAN` | Scanned from non-invoice material |

> [!NOTE]
> Scanned invoices may have lower data accuracy than electronic invoices, depending on the quality of the source document. Consider adding extra validation for scanned invoices in your integration, especially for key fields like amounts and bank account numbers. For more information about scanning services, see [Scanning](https://documentation.maventa.com/integration-guide/invoice-receiving/scanning/).

### Bank account change notifications

Maventa automatically checks the supplier bank account on each received invoice against accounts previously seen for that supplier, and can email a notification when a new bank account appears. This runs on all incoming invoices as an early warning against payment fraud and does not require the Detect service. For the Detect service's dedicated `BANK_ACCOUNT_CHANGED` check, see the [Detect page](https://documentation.maventa.com/integration-guide/invoice-receiving/detect/).

## Error handling

When building your receiving integration, handle API errors gracefully so that temporary issues do not cause missed invoices or data loss. The Maventa REST API returns errors in a consistent JSON format:

```json
{
  "code": "not_found",
  "message": "Requested resource not found or you don't have access to it",
  "details": null
}
```

### HTTP status codes for receiving endpoints

The invoice listing and download endpoints can return the following status codes:

| Status | Code | Description | Action |
|--------|------|-------------|--------|
| `200` | — | Success | Process the response normally. |
| `400` | `invalid_parameters` | Request parameters are invalid — for example, an unsupported date format or missing required parameter. | Fix the request parameters. Do not retry with the same values. |
| `400` | `invalid_format` | The requested `return_format` is not supported. | Check the list of [supported formats](https://documentation.maventa.com/integration-guide/invoicing-formats/invoicing-formats/) and correct the `return_format` value. |
| `400` | `invoice_download_api_error` | An error occurred while downloading the invoice — for example, the format conversion failed. | Log the error. If the issue is format-related, try downloading in the original format or as `PEPPOLBIS30`. |
| `401` | `auth_unauthorized` | Authentication token is missing, expired, or invalid. | Request a new OAuth2 token and retry. If the error persists, verify your credentials. |
| `403` | `forbidden` | Your account does not have permission to access this resource. | Verify that the authenticated company owns the invoice. Do not retry — this is a permanent error. |
| `403` | `vendor_api_key_missing` | The request is missing a valid vendor API key. | Include a valid `vendor_api_key` in your authentication. |
| `404` | `not_found` | The invoice or file ID does not exist, or you do not have access to it. | Verify the ID. If polling, the invoice may have been deleted or may belong to another company. Do not retry. |
| `429` | `too_many_requests` | You are sending requests too frequently. | Back off and retry after a delay. See [Retry strategy](#retry-strategy) below. |
| `500` | `internal_server_error` | An unexpected server error occurred. | Retry with exponential backoff. If the error persists, contact Maventa support. |
| `503` | `service_unavailable` | The service is temporarily unavailable due to maintenance or high load. | Retry with exponential backoff. |

### Retryable vs non-retryable errors

> [!NOTE]
> **Retryable** (use exponential backoff): `429`, `500`, `503`, and network timeouts or connection errors.
>
> **Non-retryable** (fix the request or configuration): `400`, `403`, `404`.
>
> **Special case**: `401` — retry once with a fresh token. If it fails again, the issue is with your credentials, not a transient problem.

### Retry strategy

When a retryable error occurs, use exponential backoff to avoid overloading the API:

1. **First retry** — wait 1 minute
2. **Second retry** — wait 5 minutes
3. **Third retry** — wait 30 minutes
4. **After three failures** — mark the invoice as failed and alert your operations team

Keep the invoice ID in your local list with a "pending download" status throughout the retry cycle. Do not remove it until the download succeeds or you decide to skip it.

> [!WARNING]
> Never retry `400` or `404` errors with the same parameters — these indicate a problem with the request itself, not a temporary issue. Retrying them wastes API calls and may trigger rate limiting.

### Common failure scenarios

| Scenario | Recommended approach |
|----------|---------------------|
| Download fails mid-process (XML succeeds, attachment fails) | Keep the invoice as "partially downloaded". Retry only the failed file downloads using `GET /v1/invoices/{id}/files/{file_id}`. |
| Webhook endpoint is temporarily down | Maventa retries webhook delivery once per hour for up to 24 attempts. Poll once a day as a backup to catch any gaps. See the [Webhooks guide](https://documentation.maventa.com/integration-guide/integration-tools/webhooks/) for details. |
| Duplicate invoice ID received | Check your local ID list before processing. Duplicates can occur from webhook retries or overlapping polling windows. |
| Format conversion fails (`invoice_download_api_error`) | Try downloading in the invoice's original format, or use `PEPPOLBIS30` as a fallback. Download attachments separately if needed. |
| Polling returns an error | Do not update the stored timestamp. Retry with the same time window on the next polling cycle. |

## Step 3: Fetch Detect results

If the [Detect](https://documentation.maventa.com/integration-guide/invoice-receiving/detect/) service is enabled for the company, fetch the validation and fraud check results for each received invoice.

Use [GET /v1/invoices/{id}/detect_results](https://swagger.maventa.com/#/invoices/getV1InvoicesIdDetectResults) to download the check results based on invoice ID.

The response includes results from checks such as VAT register verification, bank account change detection, and warning list cross-referencing. Use these results to flag invoices that require manual review before approval.

For more information, see the [Detect](https://documentation.maventa.com/integration-guide/invoice-receiving/detect/) service documentation and [Fraud reporting](https://documentation.maventa.com/integration-guide/invoice-receiving/fraud-reporting/).