> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.monite.com/v-2024-05-25/e-invoicing/onboarding/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server. # Entity onboarding for e-invoicing ## Overview To send or receive e-invoices, an [entity](../entities/index) 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](./index#countries). * 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. ## Considerations > **Sandbox note** > > E-invoicing connections and entity PEPPOL IDs created in the [sandbox environment](../api/concepts/environments) are erased periodically and should be considered temporary. > Other entity data in the sandbox - users, e-invoices, and so on - is preserved. ## Roles and permissions \[#permissions] The `/einvoicing_connections*` endpoints mentioned in this guide can be called both with [partner tokens](../get-started/credentials#generate-partner-token) and [entity user tokens](../entities/users#get-entity-user-token). Entity users do not need any special permissions. ## Register an entity in PEPPOL \[#registration] 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-ids#schemes). > **If an entity has both the business number and VAT number, which one to use for PEPPOL registration?** > > The country-specific regulations are as follows: > > * Belgium Peppol authority [requires](https://bosa.belgium.be/nl/BPA#:~:text=Gebruik%20van%20ondernemingsnummer%20als%20primaire%20identificatie) using the business number (KBO/BCE number) as the primary identifier. > * Dutch Peppol authority [recommends](https://www.peppolautoriteit.nl/documenten/2021/03/09/guideline-for-the-use-of-identifier-schemes-for-recipients-on-the-peppol-network) registering both KVK and VAT number. > > In general, an entity can register multiple PEPPOL identifiers. > This increases the entity's discoverability on the PEPPOL network, and allows other businesses to send e-invoices to the entity using any of the registered identifiers. > However, it comes with an additional maintenance burden to keep all of the registered identifiers up-to-date. PEPPOL registration is usually immediate. Upon successful registration, the entity is added to the public PEPPOL directory at [https://directory.peppol.eu/](https://directory.peppol.eu/) (production) or [https://test-directory.peppol.eu/](https://test-directory.peppol.eu/) (sandbox). You can confirm the entity's registration by looking it up in the corresponding directory. ![Entity information in the PEPPOL directory](/_fern-img/5a5c3dc8b292c386a5bc9e041630881e9747e30aac0a6ad64c1ab60592bc5782.webp) ### Register using VAT ID \[#register-vat-id] If the entity's VAT number has been added as a [VAT ID](../entities/vat-ids) in Monite, you can register the entity in PEPPOL using this VAT ID. To do this, call [`POST /einvoicing_connections`](/api/einvoicing-connections/post-einvoicing-connections) and specify the UUID of the entity's VAT ID and the `address` to be listed in the [pubic PEPPOL directory](https://directory.peppol.eu/public). The address would typically be the same as the address specified in the entity object, but can be different if needed. ```sh {7, 15} curl -X POST 'https://api.sandbox.monite.com/v1/einvoicing_connections' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "address": { "address_line1": "Flughafenstrasse 52", "address_line2": "", "city": "Berlin", "country": "DE", "postal_code": "10115", "state": "" }, "entity_vat_id_id": "d31b36f2-6148-4cd6-97d3-1fd90b5b0e7d" }' ``` > **Warning** > > * The address of PEPPOL registration cannot be changed. > > * Monite does not validate addresses, VAT numbers, and business numbers for PEPPOL registration. > You are responsible for the accuracy of the entity information. The [network scheme name](./index#peppol-ids) 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` for Belgium entities, e.g. `9925:BE0123456789` * `9944:NL` for Dutch entities, e.g. `9944:NL123456789B12` * `9930:DE` 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. ```json {10} { "id": "26835886-86f2-4020-ac62-07f423175ae9", "created_at": "2025-03-15T09:30:00Z", "updated_at": "2025-03-15T09:30:00Z", "address": { ... }, "credentials": [ { "id": "48d29385-e458-40ff-9429-7a857620d5db", "created_at": "2024-03-15T09:30:00Z", "updated_at": "2024-03-15T09:30:00Z", "einvoicing_connection_id": "26835886-86f2-4020-ac62-07f423175ae9", "network_credentials_identifier": "DE123456789", "network_credentials_schema": "DE:VAT" } ], "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "legal_name": "Acme GmbH", "status": "active", "provider_id": "343409" } ``` ### Register other identifiers \[#register-other-id] 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`](/api/einvoicing-connections/post-einvoicing-connections). In the request body, specify the entity's `address` to be listed in the [public PEPPOL directory](https://directory.peppol.eu/public). This address would typically be the same as the address specified in the entity object, but can be different if needed. ```sh curl -X POST 'https://api.sandbox.monite.com/v1/einvoicing_connections' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "address": { "address_line1": "Valeriusplein 122", "address_line2": "", "city": "Amsterdam", "country": "NL", "postal_code": "1075 BH", "state": "" } }' ``` This returns a Monite-assigned `id` of the e-invoicing network connection: ```json {2} { "id": "26835886-86f2-4020-ac62-07f423175ae9", ... "address": { ... }, "credentials": [], "entity_id": "cde53f99-af05-41ac-a90b-f72c5b19a605", "legal_name": "Acme", "provider_id": "343409", "status": "pending" } ``` Next, call [POST /einvoicing\_connections/\{connection\_id}/network\_credentials](/api/einvoicing-connections/post-einvoicing-connections-id-network-credentials) and specify the [PEPPOL scheme name](./index#peppol-identifiers) and the entity's identifier corresponding to that scheme: ```sh curl -X POST 'https://api.sandbox.monite.com/v1/einvoicing_connections/26835...ae9/network_credentials' \ -H 'X-Monite-Version: 2024-05-25' \ -H 'X-Monite-Entity-Id: ENTITY_ID' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "network_credentials_schema": "NL:KVK", "network_credentials_identifier": "12345678" }' ``` 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. ```json {2} { "id": "8aad8984-cefa-423f-a371-8207d9cb2ad9", ... "einvoicing_connection_id": "26835886-86f2-4020-ac62-07f423175ae9", "network_credentials_identifier": "12345678", "network_credentials_schema": "NL:KVK" } ``` **The PEPPOL ID of the entity will be:** ``` : ``` where `` is the [ICD code](./peppol-ids#schemes) corresponding to the `network_credentials_schema` used. ### Registration errors \[#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](../api/concepts/environments) 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. #### Sample error responses PEPPOL identifier already registered: ```json { "errors": [ { "source": "identifier", "details": "already exists on the test PEPPOL network" } ] } ``` ```json { "errors": [ { "source": "identifier", "details": "identifier '9930:DE123456789' already exists for mode 'pilot', usage 'usage_send_and_receive'" } ] } ``` Incorrect identifier length: ```json { "errors": [ { "source": "identifier", "details": "identifier '12345' ('0106:12345') does not match format '^\\d{6,9}$'" } ] } ``` ### Check e-invoicing onboarding status \[#check-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}`](/api/einvoicing-connections/get-einvoicing-connections-id) and examine the `status` value in the response: ```json {13} { ... "address": { ... }, "credentials": [ { ... "network_credentials_identifier": "DE12345678", "network_credentials_schema": "DE:VAT" } ], "entity_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "legal_name": "Acme GmbH", "status": "active", "provider_id": "12345" } ``` 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](../intro/support) for assistance. ## Update or remove a PEPPOL ID \[#update-or-remove-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](#deregister) 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 \[#deregister] 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}](/api/einvoicing-connections/delete-einvoicing-connections-id). This terminates the entity's registration in PEPPOL, deletes its PEPPOL IDs, and removes the entity from the [PEPPOL directory](https://directory.peppol.eu/public). 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 \[#whats-next] Once an entity has been registered in the PEPPOL network, it can: * [Send e-invoices](./send) * [Receive e-invoices](./receive)