Entity onboarding for e-invoicing

Overview

To send or receive e-invoices, an entity needs to be registered on the e-invoicing network.

Monite API allows you to automatically register your entities on the PEPPOL e-invoicing network in just a few minutes. Once done, all e-invoices sent to the entity via PEPPOL will arrive directly to the entity’s accounts payable in Monite.

Requirements

• The entity must be from a supported country.
• The entity must not already be registered in PEPPOL through another platform.

Monite cannot provide e-invoicing to entities that are already registered in PEPPOL. Such entities need to terminate their registration at the previous PEPPOL access point before they can use e-invoicing via the Monite platform.

Roles and permissions

The /einvoicing_connections* endpoints mentioned in this guide can be called both with partner tokens and entity user tokens. Entity users do not need any special permissions.

Register an entity in PEPPOL

Depending on the entity’s country, you can register the entity in PEPPOL using its business number or VAT number or both. Refer to the list of supported schemes.

PEPPOL registration is usually immediate. Upon successful registration, the entity is added to the public PEPPOL directory at https://directory.peppol.eu/ (production) or https://test-directory.peppol.eu/ (sandbox). You can confirm the entity’s registration by looking it up in the corresponding directory.

Register using VAT ID

If the entity’s VAT number has been added as a VAT ID in Monite, you can register the entity in PEPPOL using this VAT ID. To do this, call POST /einvoicing_connections and specify the UUID of the entity’s VAT ID and the address to be listed in the pubic PEPPOL directory. The address would typically be the same as the address specified in the entity object, but can be different if needed.

1
curl -X POST 'https://api.sandbox.monite.com/v1/einvoicing_connections' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
        "address": {
8
            "address_line1": "Flughafenstrasse 52",
9
            "address_line2": "",
10
            "city": "Berlin",
11
            "country": "DE",
12
            "postal_code": "10115",
13
            "state": ""
14
        },
15
        "entity_vat_id_id": "d31b36f2-6148-4cd6-97d3-1fd90b5b0e7d"
16
    }'

The network scheme name for PEPPOL registration is inferred from the address.country specified in this request (rather than from the country of the VAT ID object). For example, DE:VAT for Germany or NL:VAT for the Netherlands.

The PEPPOL ID assigned to the entity will be:

• 9925:BE<vat number digits> for Belgium entities, e.g. 9925:BE0123456789
• 9944:NL<vat number> for Dutch entities, e.g. 9944:NL123456789B12
• 9930:DE<vat number digits> for German entities, e.g. 9930:DE123456789

Note down the credentials[].id value returned in the response - you will need it later when creating e-invoices on behalf of this entity.

1
{
2
  "id": "26835886-86f2-4020-ac62-07f423175ae9",
3
  "created_at": "2025-03-15T09:30:00Z",
4
  "updated_at": "2025-03-15T09:30:00Z",
5
  "address": {
6
    ...
7
  },
8
  "credentials": [
9
    {
10
      "id": "48d29385-e458-40ff-9429-7a857620d5db",
11
      "created_at": "2024-03-15T09:30:00Z",
12
      "updated_at": "2024-03-15T09:30:00Z",
13
      "einvoicing_connection_id": "26835886-86f2-4020-ac62-07f423175ae9",
14
      "network_credentials_identifier": "DE123456789",
15
      "network_credentials_schema": "DE:VAT"
16
    }
17
  ],
18
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
19
  "legal_name": "Acme GmbH",
20
  "status": "active",
21
  "provider_id": "343409"
22
}

Register other identifiers

This approach can be used to register an entity’s business number (such as Dutch KVK) as its PEPPOL identifier.

If you have not created an e-invoicing connection for the entity yet, create one by calling POST /einvoicing_connections. In the request body, specify the entity’s address to be listed in the public PEPPOL directory. This address would typically be the same as the address specified in the entity object, but can be different if needed.

1
curl -X POST 'https://api.sandbox.monite.com/v1/einvoicing_connections' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
        "address": {
8
            "address_line1": "Valeriusplein 122",
9
            "address_line2": "",
10
            "city": "Amsterdam",
11
            "country": "NL",
12
            "postal_code": "1075 BH",
13
            "state": ""
14
        }
15
    }'

This returns a Monite-assigned id of the e-invoicing network connection:

1
{
2
  "id": "26835886-86f2-4020-ac62-07f423175ae9",
3
  ...
4
  "address": { ... },
5
  "credentials": [],
6
  "entity_id": "cde53f99-af05-41ac-a90b-f72c5b19a605",
7
  "legal_name": "Acme",
8
  "provider_id": "343409",
9
  "status": "pending"
10
}

Next, call POST /einvoicing_connections/{connection_id}/network_credentials and specify the PEPPOL scheme name and the entity’s identifier corresponding to that scheme:

1
curl -X POST 'https://api.sandbox.monite.com/v1/einvoicing_connections/26835...ae9/network_credentials' \
2
     -H 'X-Monite-Version: 2024-05-25' \
3
     -H 'X-Monite-Entity-Id: ENTITY_ID' \
4
     -H 'Authorization: Bearer ACCESS_TOKEN' \
5
     -H 'Content-Type: application/json' \
6
     -d '{
7
        "network_credentials_schema": "NL:KVK",
8
        "network_credentials_identifier": "12345678"
9
    }'

If the registration is successful, Monite returns an internal id of the entity’s PEPPOL identifier. You will need this id later when creating e-invoices on behalf of the entity.

1
{
2
  "id": "8aad8984-cefa-423f-a371-8207d9cb2ad9",
3
  ...
4
  "einvoicing_connection_id": "26835886-86f2-4020-ac62-07f423175ae9",
5
  "network_credentials_identifier": "12345678",
6
  "network_credentials_schema": "NL:KVK"
7
}

The PEPPOL ID of the entity will be:

<code>:<network_credentials_identifier>

where <code> is the ICD code corresponding to the network_credentials_schema used.

Registration errors

If the same VAT ID or business number is already registered in PEPPOL, the abovementioned API calls return an HTTP 422 error. You can usually encounter this error in the sandbox environment when trying to register random test identifiers that are already registered by other participants.

422 status is also returned if the specified identifier has incorrect length or format.

1
{
2
  "errors": [
3
    {
4
      "source": "identifier",
5
      "details": "already exists on the test PEPPOL network"
6
    }
7
  ]
8
}

1
{
2
  "errors": [
3
    {
4
      "source": "identifier",
5
      "details": "identifier '9930:DE123456789' already exists for mode 'pilot', usage 'usage_send_and_receive'"
6
    }
7
  ]
8
}

1
{
2
  "errors": [
3
    {
4
      "source": "identifier",
5
      "details": "identifier '12345' ('0106:12345') does not match format '^\\d{6,9}$'"
6
    }
7
  ]
8
}

Check e-invoicing onboarding status

Entity registration in PEPPOL is usually immediate. After at least one PEPPOL identifier has been registered, the status of the e-invoicing connection will be active. This means the entity can both send and receive e-invoices.

To check e-invoicing status, call GET /einvoicing_connections/{connection_id} and examine the status value in the response:

1
{
2
  ...
3
  "address": { ... },
4
  "credentials": [
5
    {
6
      ...
7
      "network_credentials_identifier": "DE12345678",
8
      "network_credentials_schema": "DE:VAT"
9
    }
10
  ],
11
  "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
12
  "legal_name": "Acme GmbH",
13
  "status": "active",
14
  "provider_id": "12345"
15
}

The status can be pending if you called POST /einvoicing_connections with only address and did not register any PEPPOL identifier afterwards. This is indicated by an empty credentials array in the e-invoicing connection object. To resolve the issue, call POST /einvoicing_connections/{connection_id}/network_credentials to register a PEPPOL identifier for the entity.

If the status is inactive or failed, contact us for assistance.

Update or remove a PEPPOL ID

Currently there is no way to update or remove existing PEPPOL IDs of an entity.

As a workaround, you can delete the e-invoicing connection and re-create it with the correct PEPPOL IDs. However, this temporarily terminates the entity’s PEPPOL registration which may be undesirable.

Offboarding: Deregister an entity from PEPPOL

If an entity is no longer your customer or does not want to use e-invoicing through the Monite platform, you can offboard this entity by deleting its e-invoicing connection. To do this, call DELETE /einvoicing_connections/{einvoicing_connection_id}.

This terminates the entity’s registration in PEPPOL, deletes its PEPPOL IDs, and removes the entity from the PEPPOL directory. The entity will no longer receive PEPPOL e-invoices into the Monite platform, and cannot send e-invoices as well.

Deregistration is usually immediate but may take up to one hour.

What’s next

Once an entity has been registered in the PEPPOL network, it can:

• Send e-invoices
• Receive e-invoices