Admin API - e-invoice.be

The Admin API is available only to resellers that have an organisation API key. For invoice operations with a tenant API key, see Create e-invoices.

Overview

A reseller uses the Admin API to manage tenants. A tenant is a company that a reseller manages. With the Admin API you can:

create, read, update and delete tenants
issue, read, rename and revoke the API keys of a tenant
register a tenant on the Peppol network, or keep the tenant send-only
put a test document in the inbox of a test-mode tenant

The admin operations are not in the OpenAPI specification, so the generated API reference has no pages for them. This page is the reference.

Endpoint overview

All paths are on the host https://api.e-invoice.be.

Method	Path	Purpose
`GET`	`/api/admin/ping`	Health check (no authentication)
`GET`	`/api/admin/tenants`	List tenants
`POST`	`/api/admin/tenants`	Create a tenant
`GET`	`/api/admin/tenants/{tenant_id}`	Get a tenant
`PUT`	`/api/admin/tenants/{tenant_id}`	Update a tenant
`DELETE`	`/api/admin/tenants/{tenant_id}`	Delete a tenant
`GET`	`/api/admin/tenants/{tenant_id}/api-keys`	List API keys
`POST`	`/api/admin/tenants/{tenant_id}/api-keys`	Create an API key
`GET`	`/api/admin/tenants/{tenant_id}/api-keys/latest`	Get the latest API key
`GET`	`/api/admin/tenants/{tenant_id}/api-keys/{api_key_id}`	Get one API key
`PUT`	`/api/admin/tenants/{tenant_id}/api-keys/{api_key_id}`	Update an API key
`DELETE`	`/api/admin/tenants/{tenant_id}/api-keys/{api_key_id}`	Revoke an API key
`GET`	`/api/admin/tenants/{tenant_id}/peppol/`	Check the registration status
`POST`	`/api/admin/tenants/{tenant_id}/peppol/register`	Register on Peppol
`PUT`	`/api/admin/tenants/{tenant_id}/peppol/business-card`	Update the business card
`DELETE`	`/api/admin/tenants/{tenant_id}/peppol/unregister`	Unregister from Peppol
`POST`	`/api/admin/tenants/{tenant_id}/simulate-inbound`	Simulate an inbound document

Authentication

Send the organisation API key as a bearer token. A tenant API key does not give access to the Admin API.

curl -X GET "https://api.e-invoice.be/api/admin/tenants" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY"

The samples on this page read the organisation API key from the environment variable E_INVOICE_ORG_API_KEY. Samples that use a tenant API key read it from E_INVOICE_API_KEY. An organisation API key gives access only to the tenants of that organisation. A request for a tenant of a different organisation returns 404 Not Found.

Only approved resellers get an organisation API key. Send an email to support@e-invoice.be to apply for the reseller programme.

Health check

GET /api/admin/ping shows that the Admin API is available. This request needs no authentication.

curl -X GET "https://api.e-invoice.be/api/admin/ping"

{
  "message": "Pong",
  "status": "ok",
  "timestamp": "2026-04-16T10:00:00.123456"
}

Tenant management

List tenants

Get the tenants of your organisation, newest first. Deleted tenants are not in the list.

curl -X GET "https://api.e-invoice.be/api/admin/tenants?skip=0&limit=100" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY"

integer

default:"0"

Number of tenants to skip.

integer

default:"100"

Maximum number of tenants to return.

{
  "tenants": [
    {
      "name": "e-invoice-bv",
      "description": "E-INVOICE BV",
      "plan": "enterprise",
      "credit_balance": 999999999,
      "peppol_ids": ["0208:1018265814"],
      "ibans": null,
      "company_number": "1018265814",
      "company_tax_id": "BE1018265814",
      "company_name": "E-INVOICE BV",
      "company_address": null,
      "company_zip": null,
      "company_city": null,
      "company_country": "BE",
      "company_email": "info@e-invoice.be",
      "smp_registration": false,
      "smp_registration_date": null,
      "bcc_recipient_email": null,
      "id": "ten-9k2m4p7q3w5x8r1t",
      "created_at": "2026-04-16T10:00:00.000000Z",
      "updated_at": "2026-04-16T10:00:00.000000Z",
      "enrollment_state": "not_required",
      "status_message": null,
      "route_override": null
    }
  ],
  "total": 1
}

total is the number of tenants that are not deleted, not the number of tenants in this page.

Create a tenant

curl -X POST "https://api.e-invoice.be/api/admin/tenants" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "e-invoice-bv",
       "description": "E-INVOICE BV",
       "company_number": "1018265814",
       "company_tax_id": "BE1018265814",
       "company_name": "E-INVOICE BV",
       "company_country": "BE",
       "company_email": "info@e-invoice.be",
       "peppol_ids": ["0208:1018265814"]
     }'

const response = await fetch('https://api.e-invoice.be/api/admin/tenants', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.E_INVOICE_ORG_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'e-invoice-bv',
    description: 'E-INVOICE BV',
    company_number: '1018265814',
    company_tax_id: 'BE1018265814',
    company_name: 'E-INVOICE BV',
    company_country: 'BE',
    company_email: 'info@e-invoice.be',
    peppol_ids: ['0208:1018265814'],
  }),
});

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

const tenant = await response.json();
console.log(tenant.id);

import os

import requests

response = requests.post(
    "https://api.e-invoice.be/api/admin/tenants",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_ORG_API_KEY']}"},
    json={
        "name": "e-invoice-bv",
        "description": "E-INVOICE BV",
        "company_number": "1018265814",
        "company_tax_id": "BE1018265814",
        "company_name": "E-INVOICE BV",
        "company_country": "BE",
        "company_email": "info@e-invoice.be",
        "peppol_ids": ["0208:1018265814"],
    },
    timeout=30,
)
response.raise_for_status()

tenant = response.json()
print(tenant["id"])

<?php
$body = json_encode([
    'name' => 'e-invoice-bv',
    'description' => 'E-INVOICE BV',
    'company_number' => '1018265814',
    'company_tax_id' => 'BE1018265814',
    'company_name' => 'E-INVOICE BV',
    'company_country' => 'BE',
    'company_email' => 'info@e-invoice.be',
    'peppol_ids' => ['0208:1018265814'],
]);

$ch = curl_init('https://api.e-invoice.be/api/admin/tenants');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('E_INVOICE_ORG_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 201) {
    throw new RuntimeException("$status: $result");
}

$tenant = json_decode($result, true);
echo $tenant['id'];

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

using var client = new HttpClient { BaseAddress = new Uri("https://api.e-invoice.be") };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("E_INVOICE_ORG_API_KEY"));

var response = await client.PostAsJsonAsync("/api/admin/tenants", new
{
    name = "e-invoice-bv",
    description = "E-INVOICE BV",
    company_number = "1018265814",
    company_tax_id = "BE1018265814",
    company_name = "E-INVOICE BV",
    company_country = "BE",
    company_email = "info@e-invoice.be",
    peppol_ids = new[] { "0208:1018265814" },
});
response.EnsureSuccessStatusCode();

var tenant = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(tenant.GetProperty("id").GetString());

Request fields

Only name is required. All other fields are optional.

string

required

Name of the tenant. The name must be unique among the tenants of your organisation that are not deleted. A name that is in use gives 409 Conflict. The API does not apply a format rule. A lower-case name without spaces, for example a slug of the company name, is a good convention.

string

Free text that describes the tenant.

string

default:"enterprise"

Plan of the tenant: starter, pro or enterprise. See Plans and credits.

integer

default:"999999999"

Credit balance of the tenant. See Plans and credits.

string[]

The Peppol ID of the tenant in the form scheme:identifier. The field is an array, but the platform uses one Peppol ID for each tenant. The tenant needs it to create and send documents: if the sender Peppol ID of a document is not in this list, POST /api/documents/ returns 406 and POST /api/documents/{document_id}/send returns 409. See Why you set the Peppol ID when you create the tenant.

string[]

IBANs of the tenant.

string

Company registration number from the national business register, without a country prefix. For Belgium this is the CBE number, for example 1018265814.

string

VAT number, with the country prefix, for example BE1018265814. The API removes spaces and the characters ., -, / and _, and changes letters to upper case: BE 1018.265.814 becomes BE1018265814. A different character, for example (, gives 422 Unprocessable Entity.

string

Legal name of the company, with the company type, for example E-INVOICE BV.

string

Street and number, for example Brusselsesteenweg 119.

string

Postal code, for example 1980.

string

City, for example Zemst.

string

Country of the company as a two-letter ISO 3166-1 code in upper case, for example BE. The API uses this value to select the delivery route of the outbound documents of the tenant, so do not write the country name.

string

Contact email address of the tenant. For a test-mode tenant this field is necessary: the API sends each outbound document to this address. Without it, each send of the tenant fails with 400 Bad Request. See Contact email address of a test-mode tenant.

The API ignores fields that are not in this list. You cannot set test_mode (see below). route_override is accepted only by Update a tenant; create ignores it. The response has the status 201 Created:

{
  "name": "e-invoice-bv",
  "description": "E-INVOICE BV",
  "plan": "enterprise",
  "credit_balance": 999999999,
  "peppol_ids": ["0208:1018265814"],
  "ibans": null,
  "company_number": "1018265814",
  "company_tax_id": "BE1018265814",
  "company_name": "E-INVOICE BV",
  "company_address": null,
  "company_zip": null,
  "company_city": null,
  "company_country": "BE",
  "company_email": "info@e-invoice.be",
  "smp_registration": false,
  "smp_registration_date": null,
  "bcc_recipient_email": "e-invoice-bv+3f9a1c7e@outbox.email.e-invoice.be",
  "id": "ten-9k2m4p7q3w5x8r1t",
  "created_at": "2026-04-16T10:00:00.000000Z",
  "updated_at": "2026-04-16T10:00:00.000000Z",
  "enrollment_state": "not_required",
  "status_message": null,
  "route_override": null
}

You must find and set the correct Peppol ID for each tenant. The API does not validate peppol_ids when you create or update a tenant. Creating a tenant does not register the Peppol ID on the Peppol network; see Register on Peppol.

A tenant that you create with the organisation API key of a test-mode organisation is a test-mode tenant. The request body has no test_mode field. You cannot change the test mode of a tenant after you create it. See Test mode and sandbox companies.

Contact email address of a test-mode tenant

A test-mode tenant does not send documents on the Peppol network. The API sends each outbound document as an email with the UBL XML to the company_email of the tenant. Set company_email when you create a test-mode tenant. If company_email is not set, POST /api/documents/{document_id}/send returns 400 Bad Request:

{
  "detail": "Tenant is in test mode but no company email is set"
}

The API sends no email and no webhook event. But the API changes the state of the document to SENT, so a second send of the same document returns 405. To correct the problem:

Set the contact email address

Call Update a tenant with {"company_email": "info@e-invoice.be"}. Use an address that you can read.

Create the document again

Create a new document with POST /api/documents/ and send it.

Tenant response fields

Each tenant operation returns the request fields above and these fields:

string

Identifier of the tenant. Use it as tenant_id in the paths.

string

Date and time when the tenant was created.

string

Date and time of the last change.

boolean

Whether the tenant is registered on the SMP (Service Metadata Publisher) of e-invoice.be.

string | null

Date and time of the registration on the SMP.

string | null

Email address of the tenant at outbox.email.e-invoice.be. The create and get operations fill this field.

string

Activation state of the tenant for its destination network: not_required, not_enrolled, pending, enrolled or failed. A tenant that sends through Peppol has not_required and can send immediately.

string | null

The reason when enrollment_state is failed.

string | null

The delivery route that is set with Update a tenant. null when the tenant uses the default delivery route for its company_country.

Company number and tax ID

The two fields have different formats. The API does not report an error when you mix them up, so check the format in your system.

company_number is the registration number from the national business register, without a country prefix (Belgium: CBE number 1018265814, Netherlands: KvK number).
company_tax_id is the VAT number with the country prefix (BE1018265814, NL123456789B01).

For a Belgian company, the Peppol ID is 0208: plus the CBE number:

Field	Value
`company_number`	`1018265814`
`company_tax_id`	`BE1018265814`
`peppol_ids`	`["0208:1018265814"]`

For the schemes of other countries, see Look up Peppol participants and Supported schemes.

Why you set the Peppol ID when you create the tenant

The API uses the Peppol ID in peppol_ids for three functions:

Creating and sending. POST /api/documents/ accepts a document only when the sender Peppol ID is in the peppol_ids of the tenant (if not: 406). POST /api/documents/{document_id}/send does the same check (if not: 409). For a self-billing document, the Peppol sender is the customer, so the check applies to the customer_* fields. The comparison ignores letter case and spaces at the start and the end.
Receiving. Documents for the Peppol ID go to the tenant, after the ID is registered.
Registration. Register on Peppol publishes the ID on the SMP and in the Peppol Directory.

Tenant create and tenant update do not write to the SMP or the SML (Service Metadata Locator). Registration is a separate step. Do it when the tenant must receive documents, or do not do it for a send-only tenant.

Get a tenant

curl -X GET "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY"

The response has the same shape as the response of Create a tenant. This operation also returns a tenant that is deleted.

{
  "name": "e-invoice-bv",
  "description": "E-INVOICE BV",
  "plan": "enterprise",
  "credit_balance": 999999999,
  "peppol_ids": ["0208:1018265814"],
  "ibans": null,
  "company_number": "1018265814",
  "company_tax_id": "BE1018265814",
  "company_name": "E-INVOICE BV",
  "company_address": null,
  "company_zip": null,
  "company_city": null,
  "company_country": "BE",
  "company_email": "info@e-invoice.be",
  "smp_registration": false,
  "smp_registration_date": null,
  "bcc_recipient_email": "e-invoice-bv+3f9a1c7e@outbox.email.e-invoice.be",
  "id": "ten-9k2m4p7q3w5x8r1t",
  "created_at": "2026-04-16T10:00:00.000000Z",
  "updated_at": "2026-04-16T10:00:00.000000Z",
  "enrollment_state": "not_required",
  "status_message": null,
  "route_override": null
}

Update a tenant

Send only the fields that you want to change. The API keeps the value of each field that is not in the request body. When you send a field with the value null, the API clears the field. Do not send null for name, plan or credit_balance. This operation also changes a tenant that is deleted. The request accepts all the request fields of Create a tenant, with these differences:

name is optional.
route_override is accepted. Create ignores this field.
test_mode is not accepted. The test mode of a tenant does not change.

string | null

Sets the delivery route of the outbound documents of the tenant, instead of the default route for its company_country. The values are peppol-direct and fr-superpdp. A different value gives 422 Unprocessable Entity. Send null to use the default route again.

This example adds the contact email address and an IBAN:

curl -X PUT "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "description": "E-INVOICE BV - accounting integration",
       "company_email": "info@e-invoice.be",
       "ibans": ["BE68539007547034"]
     }'

The response has the status 200 OK and contains the full tenant:

{
  "name": "e-invoice-bv",
  "description": "E-INVOICE BV - accounting integration",
  "plan": "enterprise",
  "credit_balance": 999999999,
  "peppol_ids": ["0208:1018265814"],
  "ibans": ["BE68539007547034"],
  "company_number": "1018265814",
  "company_tax_id": "BE1018265814",
  "company_name": "E-INVOICE BV",
  "company_address": null,
  "company_zip": null,
  "company_city": null,
  "company_country": "BE",
  "company_email": "info@e-invoice.be",
  "smp_registration": false,
  "smp_registration_date": null,
  "bcc_recipient_email": null,
  "id": "ten-9k2m4p7q3w5x8r1t",
  "created_at": "2026-04-16T10:00:00.000000Z",
  "updated_at": "2026-04-16T11:30:00.000000Z",
  "enrollment_state": "not_required",
  "status_message": null,
  "route_override": null
}

A new name that a different tenant of your organisation already has gives 409 Conflict.

Delete a tenant

This operation marks the tenant as deleted. It does not remove the data of the tenant.

curl -X DELETE "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY"

The response has the status 204 No Content and no body:

HTTP/1.1 204 No Content

After the delete, List tenants does not show the tenant, and you can give its name to a new tenant. Get a tenant continues to return the tenant with 200 OK. The response has no field that shows that the tenant is deleted.

Delete does not unregister the tenant from Peppol and does not revoke the API keys of the tenant. Before you delete a tenant, call Unregister from Peppol when the tenant is registered. Then call Revoke an API key for each API key of the tenant.

Plans and credits

You set the plan and the credit balance of a tenant with the fields plan and credit_balance of Create a tenant and Update a tenant. These two fields are the only plan and billing functions in the Admin API.

Field	Values	Default
`plan`	`starter`, `pro`, `enterprise`	`enterprise`
`credit_balance`	Integer	`999999999`

curl -X PUT "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "plan": "pro",
       "credit_balance": 5000
     }'

The response is the full tenant with the new values (shortened here):

{
  "name": "e-invoice-bv",
  "plan": "pro",
  "credit_balance": 5000,
  "id": "ten-9k2m4p7q3w5x8r1t"
}

The tenant sees these values in GET /api/me/. GET /api/stats with the API key of the tenant returns the usage of the tenant and uses credit_balance to calculate budget_estimation_days. See Usage statistics and credits.

API key management

Create an API key

curl -X POST "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/api-keys" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "production-key",
       "description": "Production API key for E-INVOICE BV"
     }'

const tenantId = 'ten-9k2m4p7q3w5x8r1t';

const response = await fetch(
  `https://api.e-invoice.be/api/admin/tenants/${tenantId}/api-keys`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.E_INVOICE_ORG_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'production-key',
      description: 'Production API key for E-INVOICE BV',
    }),
  },
);

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

// The id is the bearer token of the tenant. Store it in a secure location.
const apiKey = await response.json();

import os

import requests

tenant_id = "ten-9k2m4p7q3w5x8r1t"

response = requests.post(
    f"https://api.e-invoice.be/api/admin/tenants/{tenant_id}/api-keys",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_ORG_API_KEY']}"},
    json={
        "name": "production-key",
        "description": "Production API key for E-INVOICE BV",
    },
    timeout=30,
)
response.raise_for_status()

# The id is the bearer token of the tenant. Store it in a secure location.
api_key = response.json()

<?php
$tenantId = 'ten-9k2m4p7q3w5x8r1t';

$ch = curl_init("https://api.e-invoice.be/api/admin/tenants/$tenantId/api-keys");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('E_INVOICE_ORG_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'production-key',
        'description' => 'Production API key for E-INVOICE BV',
    ]),
]);

$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 201) {
    throw new RuntimeException("$status: $result");
}

// The id is the bearer token of the tenant. Store it in a secure location.
$apiKey = json_decode($result, true);

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var tenantId = "ten-9k2m4p7q3w5x8r1t";

using var client = new HttpClient { BaseAddress = new Uri("https://api.e-invoice.be") };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("E_INVOICE_ORG_API_KEY"));

var response = await client.PostAsJsonAsync($"/api/admin/tenants/{tenantId}/api-keys", new
{
    name = "production-key",
    description = "Production API key for E-INVOICE BV",
});
response.EnsureSuccessStatusCode();

// The id is the bearer token of the tenant. Store it in a secure location.
var apiKey = await response.Content.ReadFromJsonAsync<JsonElement>();

string

required

Name of the API key. The name must be unique among the active API keys of the tenant; a name that is in use gives 409 Conflict.

string

Free text, for example the purpose of the key.

The response has the status 201 Created:

{
  "id": "api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y",
  "tenant_id": "ten-9k2m4p7q3w5x8r1t",
  "name": "production-key",
  "description": "Production API key for E-INVOICE BV",
  "created_at": "2026-04-16T10:00:00.000000Z",
  "updated_at": "2026-04-16T10:00:00.000000Z",
  "is_deleted": false
}

The id field is the API key. There is no separate key field. Your customer sends the value of id as the bearer token:

Authorization: Bearer api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y

Keep the id secret. Store it encrypted and give it to your customer through a secure channel. Do not write it to logs, to version control or to client-side code.

List API keys

Get the active API keys of a tenant, newest first. Revoked keys are not in the list.

curl -X GET "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/api-keys?skip=0&limit=100" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY"

integer

default:"0"

Number of API keys to skip.

integer

default:"100"

Maximum number of API keys to return.

{
  "api_keys": [
    {
      "id": "api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y",
      "tenant_id": "ten-9k2m4p7q3w5x8r1t",
      "name": "production-key",
      "description": "Production API key for E-INVOICE BV",
      "created_at": "2026-04-16T10:00:00.000000Z",
      "updated_at": "2026-04-16T10:00:00.000000Z",
      "is_deleted": false
    }
  ],
  "total": 1
}

The id is the bearer token, so the operations that read API keys return live credentials. Limit who can call them, do not write the response body to logs, and do not show it to end users.

Get the latest API key

Get the active API key of a tenant that was created last.

curl -X GET "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/api-keys/latest" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY"

{
  "id": "api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y",
  "tenant_id": "ten-9k2m4p7q3w5x8r1t",
  "name": "production-key",
  "description": "Production API key for E-INVOICE BV",
  "created_at": "2026-04-16T10:00:00.000000Z",
  "updated_at": "2026-04-16T10:00:00.000000Z",
  "is_deleted": false
}

If the tenant has no active API key, the response is 404 Not Found:

{
  "detail": "No active API keys found for tenant ten-9k2m4p7q3w5x8r1t"
}

Get one API key

Get one API key by its ID. Use this operation to see if a key is active or revoked: unlike the list operation, it also returns a revoked key, with is_deleted: true.

curl -X GET "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/api-keys/api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY"

Response for an active key:

{
  "id": "api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y",
  "tenant_id": "ten-9k2m4p7q3w5x8r1t",
  "name": "production-key",
  "description": "Production API key for E-INVOICE BV",
  "created_at": "2026-04-16T10:00:00.000000Z",
  "updated_at": "2026-04-16T10:00:00.000000Z",
  "is_deleted": false
}

Response for a revoked key:

{
  "id": "api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y",
  "tenant_id": "ten-9k2m4p7q3w5x8r1t",
  "name": "production-key",
  "description": "Production API key for E-INVOICE BV",
  "created_at": "2026-04-16T10:00:00.000000Z",
  "updated_at": "2026-04-16T10:00:00.000000Z",
  "is_deleted": true
}

If the key does not exist for this tenant, the response is 404 Not Found:

{
  "detail": "API key with ID api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y not found for tenant ten-9k2m4p7q3w5x8r1t"
}

Update an API key

Change the name or the description of an API key. The id (the bearer token) does not change.

curl -X PUT "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/api-keys/api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "production-key-v2",
       "description": "Production API key, second version"
     }'

string

New name. A name that a different active key of the tenant has gives 409 Conflict.

string

New description.

{
  "id": "api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y",
  "tenant_id": "ten-9k2m4p7q3w5x8r1t",
  "name": "production-key-v2",
  "description": "Production API key, second version",
  "created_at": "2026-04-16T10:00:00.000000Z",
  "updated_at": "2026-04-16T11:30:00.000000Z",
  "is_deleted": false
}

Revoke an API key

curl -X DELETE "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/api-keys/api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY"

The response has the status 204 No Content and no body:

HTTP/1.1 204 No Content

The key stops working immediately: a request with it returns 401. After this call, Get one API key returns the key with is_deleted: true.

Rotate an API key

Create a new API key

Call Create an API key with a new name. Keep the returned id.

Give the new key to your customer

Send the key through a secure channel, or change the configuration that you keep for the customer.

Revoke the old key

When the customer uses the new key, call Revoke an API key for the old key. The two keys are valid together until this step, so there is no downtime.

Peppol registration

Peppol registration publishes the Peppol ID of a tenant on the SMP of e-invoice.be, so that the tenant can receive documents through e-invoice.be. A tenant that only sends documents does not need a registration; see Send-only tenants.

The Peppol operations are not available with the organisation API key of a test-mode organisation. The four operations in this section then return 403 Forbidden:

{
  "detail": "Peppol operations are not available for organizations in test mode. Please contact support to enable production mode."
}

Check the registration status

curl -X GET "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/peppol/" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY"

boolean

default:"false"

Set to true to do a live check on the network. See Verify a registration.

{
  "peppol_id": "0208:1018265814",
  "state": "e-invoice",
  "smp": {
    "service_group": {
      "participant_identifier": "1018265814",
      "participant_scheme": "0208",
      "service_metadata_references": []
    },
    "business_card": {
      "participant_identifier": "1018265814",
      "participant_scheme": "0208",
      "business_entity": {
        "name": "E-INVOICE BV",
        "country_code": "BE",
        "vat_identifier": "BE1018265814",
        "website_uri": "https://e-invoice.be/company/1018265814",
        "contact": {
          "name": null,
          "email": "support@e-invoice.be"
        }
      }
    },
    "document_types": [
      {
        "document_type_code": "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",
        "endpoints": []
      }
    ]
  },
  "last_checked_at": "2026-04-16T10:00:00.000000",
  "verified": false,
  "publications": [
    {
      "peppol_id": "0208:1018265814",
      "state": "published",
      "latest_event": "directory_entry_created",
      "source": "phoss",
      "detail": null,
      "observed_at": "2026-04-16T09:55:00.000000Z"
    }
  ]
}

string

e-invoice: the Peppol ID is on the SMP of e-invoice.be. other: the Peppol ID is found on the network, but not on the SMP of e-invoice.be. not_registered: the Peppol ID is not found. A tenant with other or not_registered can send documents.

object

The service group, the business card and the document types on the SMP of e-invoice.be. The three fields are null when the Peppol ID is not on this SMP.

boolean

true when this request did a live check (verify=true).

object[]

One entry for each Peppol ID of the tenant. state is not_published, pending or published and comes from the last recorded event for the ID. latest_event, source, detail and observed_at describe that event; they are null when the ID has no events.

If the tenant has no Peppol ID, the response is 400 Bad Request:

{
  "detail": "Tenant does not have a Peppol ID"
}

Verify a registration

Without verify, the publications field comes from the events that the API recorded before (for example at registration). With verify=true, the API first does a live DNS lookup for each Peppol ID of the tenant, records the result as a new event, and then returns the status.

curl -X GET "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/peppol/?verify=true" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY"

The response has the same shape as Check the registration status. verified is true, and each publication shows the result of the live check (the smp object is shortened here):

{
  "peppol_id": "0208:1018265814",
  "state": "e-invoice",
  "smp": {
    "service_group": {
      "participant_identifier": "1018265814",
      "participant_scheme": "0208",
      "service_metadata_references": []
    },
    "business_card": null,
    "document_types": []
  },
  "last_checked_at": "2026-04-16T10:00:00.000000",
  "verified": true,
  "publications": [
    {
      "peppol_id": "0208:1018265814",
      "state": "published",
      "latest_event": "publication_verified",
      "source": "dns",
      "detail": null,
      "observed_at": "2026-04-16T10:00:00.000000Z"
    }
  ]
}

When the live check does not find the Peppol ID on the SMP of e-invoice.be, the publication has state: "not_published" and latest_event: "not_found_on_smp".

A request with verify=true adds events to the registration history of the tenant. Use it after a registration or when you examine a problem, not for frequent polling.

Register on Peppol

curl -X POST "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/peppol/register" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "peppol_id": "0208:1018265814"
     }'

const tenantId = 'ten-9k2m4p7q3w5x8r1t';

const response = await fetch(
  `https://api.e-invoice.be/api/admin/tenants/${tenantId}/peppol/register`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.E_INVOICE_ORG_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ peppol_id: '0208:1018265814' }),
  },
);

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

const registration = await response.json();
console.log(registration.success, registration.registration.method);

import os

import requests

tenant_id = "ten-9k2m4p7q3w5x8r1t"

response = requests.post(
    f"https://api.e-invoice.be/api/admin/tenants/{tenant_id}/peppol/register",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_ORG_API_KEY']}"},
    json={"peppol_id": "0208:1018265814"},
    timeout=60,
)
response.raise_for_status()

registration = response.json()
print(registration["success"], registration["registration"]["method"])

<?php
$tenantId = 'ten-9k2m4p7q3w5x8r1t';

$ch = curl_init("https://api.e-invoice.be/api/admin/tenants/$tenantId/peppol/register");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('E_INVOICE_ORG_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['peppol_id' => '0208:1018265814']),
]);

$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("$status: $result");
}

$registration = json_decode($result, true);
echo $registration['registration']['method'];

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;

var tenantId = "ten-9k2m4p7q3w5x8r1t";

using var client = new HttpClient { BaseAddress = new Uri("https://api.e-invoice.be") };
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("E_INVOICE_ORG_API_KEY"));

var response = await client.PostAsJsonAsync(
    $"/api/admin/tenants/{tenantId}/peppol/register",
    new { peppol_id = "0208:1018265814" });
response.EnsureSuccessStatusCode();

var registration = await response.Content.ReadFromJsonAsync<JsonElement>();
Console.WriteLine(registration.GetProperty("registration").GetProperty("method").GetString());

string

required

Peppol ID to register, in the form scheme:identifier. The scheme must be one of the supported schemes. The API changes the ID to lower case and removes spaces at the start and the end.

boolean

default:"false"

Set to true to do all checks and make no change on the SMP. See Dry run.

The API does these steps:

It checks the scheme and the format of the identifier.
It looks for the Peppol ID on the network. An ID that is active at a different access point gives 409 Conflict.
It creates the service group on the SMP.
It adds the six default document types: invoice, credit note, self-billing invoice, self-billing credit note, invoice response and message level response.
It adds a business card. For a Belgian Peppol ID, the company data comes from the KBO (Crossroads Bank for Enterprises).

The response has the status 200 OK:

{
  "success": true,
  "peppol_id": "0208:1018265814",
  "company_data": {
    "company_number": "1018265814",
    "company_name": "E-INVOICE BV",
    "company_country": "BE",
    "company_address": "Brusselsesteenweg 119",
    "company_zip": "1980",
    "company_city": "Zemst"
  },
  "registration": {
    "registered": true,
    "method": "direct_registration",
    "migration_result": null,
    "message": null
  },
  "business_card": {
    "success": true,
    "business_card_data": {
      "name": "E-INVOICE BV",
      "country_code": "BE",
      "geographical_information": "Zemst, BE",
      "vat_number": "BE1018265814",
      "website_url": "https://e-invoice.be/company/1018265814",
      "contact_email": "support@e-invoice.be"
    },
    "message": null,
    "error": null,
    "error_type": null,
    "dry_run": null
  },
  "document_endpoints": {
    "success": true,
    "message": "Document endpoints added successfully",
    "error": null,
    "error_type": null,
    "dry_run": null
  }
}

For a Belgian Peppol ID, company_data also contains the KBO fields status, juridical_situation, type_of_enterprise, juridical_form, start_date and address_type. For other countries, company_data contains only company_number; the other fields are null. The operation is idempotent. If the Peppol ID is already on the SMP of e-invoice.be, registration.method is already_exists and the API makes no new service group.

Status	Cause
`400 Bad Request`	The Peppol ID has an incorrect format, the scheme is not supported, or the identifier does not obey the rules of the scheme.
`403 Forbidden`	The organisation is in test mode.
`409 Conflict`	The Peppol ID is active at a different access point.
`502 Bad Gateway`	An external service (the SMP) failed. Try again later.

Dry run

With "dry_run": true, the API does the checks of a registration (scheme, identifier format, lookup on the network, KBO lookup for Belgium) and makes no change on the SMP. Use it to find an incorrect or already registered Peppol ID before the real registration.

curl -X POST "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/peppol/register" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "peppol_id": "0208:1018265814",
       "dry_run": true
     }'

{
  "success": true,
  "peppol_id": "0208:1018265814",
  "company_data": {
    "company_number": "1018265814",
    "company_name": "E-INVOICE BV",
    "company_country": "BE",
    "company_address": "Brusselsesteenweg 119",
    "company_zip": "1980",
    "company_city": "Zemst"
  },
  "registration": {
    "registered": true,
    "method": "direct_registration",
    "migration_result": null,
    "message": null
  },
  "business_card": {
    "success": true,
    "business_card_data": null,
    "message": "DRY RUN: Would add business card",
    "error": null,
    "error_type": null,
    "dry_run": true
  },
  "document_endpoints": {
    "success": true,
    "message": "DRY RUN: Would add document endpoints",
    "error": null,
    "error_type": null,
    "dry_run": true
  }
}

In a dry run, registration.registered is true although nothing is registered. Read business_card.dry_run and document_endpoints.dry_run to identify a dry-run response. A dry run does not add events to publications.

For a test-mode tenant, the API always does a dry run, whatever the value of dry_run. Update the business card and Unregister from Peppol return {"success": true} for a test-mode tenant and make no change on the SMP.

Supported schemes

Registration accepts a Peppol ID only when its scheme is in this list. The list is smaller than the list of schemes that you can send to.

Country	Scheme	Identifier
Belgium (BE)	`0208`	Enterprise number (CBE), 10 digits with a valid check digit
Netherlands (NL)	`0106`, `0190`, `9944`	KvK number, OIN (government), VAT number
Finland (FI)	`0216`	OVT code
Norway (NO)	`0192`	Organisasjonsnummer
Sweden (SE)	`0007`	Organisationsnummer
Denmark (DK)	`0184`, `0198`	CVR number, SE number
Iceland (IS)	`0196`	Kennitala
Spain (ES)	`9920`	VAT number
Ireland (IE)	`9935`	VAT number
Greece (GR)	`9933`	VAT number
Poland (PL)	`9945`	VAT number
Portugal (PT)	`9946`	VAT number
Bulgaria (BG)	`9926`	VAT number
Cyprus (CY)	`9928`	VAT number
Czech Republic (CZ)	`9929`	VAT number
Croatia (HR)	`9934`	VAT number
Hungary (HU)	`9910`	VAT number
Malta (MT)	`9943`	VAT number
Romania (RO)	`9947`	VAT number
Slovenia (SI)	`9949`	VAT number
Slovakia (SK)	`9950`	VAT number
Liechtenstein (LI)	`9936`	VAT number
Luxembourg (LU)	`9938`, `0240`	VAT number or matricule, matricule (register of legal persons)
All countries	`0088`	Global Location Number (GLN)

Schemes of other countries (for example Germany, Austria, Italy, Estonia, Latvia and Lithuania), the Belgian VAT scheme 9925 and the Finnish scheme 0037 are not accepted. The French schemes (0002, 0009, 0225, 9957) are accepted only for an organisation that has the French capability, and only after the enrolment of the tenant; send an email to support@e-invoice.be. A scheme that is not supported gives 400 Bad Request:

{
  "detail": "This Peppol ID is currently not supported and cannot be registered. Contact support@e-invoice.be"
}

The company data lookup (KBO) is for Belgium only. For a Peppol ID of a different country, the API has no company name, so the business card gets only the country of the scheme. The register request has no field for the company name. Set the name with Update the business card after the registration. The scheme codes are from the Peppol participant identifier scheme code list, version 9.7. This is the version that the API uses. For the table of the most frequent schemes that you can send to, see Look up Peppol participants.

Update the business card

Change the company name on the business card of a registered Peppol ID. The name is the only field that you can change.

curl -X PUT "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/peppol/business-card" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "peppol_id": "0208:1018265814",
       "name": "E-INVOICE BV"
     }'

string

required

Peppol ID of the business card. It must be in the peppol_ids of the tenant; if not, the response is 403 Forbidden.

string

New company name. Include the company type, for example BV or NV.

{
  "success": true
}

If the Peppol ID has no business card on the SMP, the response is 400 Bad Request:

{
  "detail": "No existing business card found for this Peppol ID"
}

The response is also 400 Bad Request in these conditions:

The tenant has no Peppol ID.
The scheme is not a supported scheme.
The identifier does not obey the rules of the scheme.

A failure of the SMP gives 502 Bad Gateway.

Unregister from Peppol

Remove the document types, the business card and the service group of a Peppol ID from the SMP of e-invoice.be. The tenant can then not receive documents through e-invoice.be. It can continue to send documents as a send-only tenant.

curl -X DELETE "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/peppol/unregister" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "peppol_id": "0208:1018265814"
     }'

string

required

Peppol ID to unregister. It must be in the peppol_ids of the tenant; if not, the response is 403 Forbidden.

{
  "success": true,
  "warnings": null
}

The operation is idempotent. If the Peppol ID was already removed, the response is:

{
  "success": true,
  "warnings": ["Participant was already unregistered"]
}

The scheme must be a supported scheme. The identifier must obey the rules of the scheme. If not, the response is 400 Bad Request. A failure of the SMP gives 502 Bad Gateway. Unregister changes no field of the tenant. The Peppol ID stays in peppol_ids, so the tenant can continue to send documents with it. In Check the registration status, the publication of the ID then has state: "not_published" and latest_event: "manually_removed".

Send-only tenants

A tenant can send documents through Peppol without a registration on the SMP and the SML. Use a send-only tenant when the company receives its documents through a different access point, or does not want to receive documents at this time. There is no send_only field. A tenant is send-only because Register on Peppol was not called for it.

Create a send-only tenant

Create the tenant

Call Create a tenant and put the Peppol ID in peppol_ids.

Create an API key

Call Create an API key for the tenant. The returned id is the bearer token of the tenant.

Send documents with the tenant API key

Create a document with POST /api/documents/ and send it. See Create e-invoices. Do not call the register operation.

curl -X POST "https://api.e-invoice.be/api/documents/doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d/send?sender_peppol_scheme=0208&sender_peppol_id=1018265814&receiver_peppol_scheme=0208&receiver_peppol_id=0848934496" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY"

The response has the status 200 OK and contains the document. This example shows the first fields:

{
  "id": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "state": "TRANSIT",
  "direction": "OUTBOUND"
}

The API does not validate peppol_ids when you create or update a tenant. It accepts an incorrect Peppol ID, for example a 0208 number with 9 digits or with an incorrect check digit. The register operation is the only step that validates the ID, and you do not call it for a send-only tenant. Validate the Peppol ID in your system before you create the tenant.

A French send-only tenant must be enrolled, but it can have zero publications. Send an email to support@e-invoice.be for the enrolment procedure.

What a send-only tenant can do

Capability	Send-only tenant
Send invoices and credit notes	Possible. The API only checks that the sender Peppol ID is in the `peppol_ids` of the tenant.
Send self-billing documents	Possible. The tenant is the customer and the Peppol sender. The check applies to the Peppol ID from the `customer_*` fields.
Receive documents through e-invoice.be	Not possible. The Peppol ID is not published, so senders cannot find it, or they find the registration at a different access point.

If the sender Peppol ID (for self-billing documents: the Peppol ID from the customer_* fields) is not in the peppol_ids of the tenant, the send request fails with 409 Conflict:

{
  "detail": "Derived sender '0208:0848934496' is not in tenant peppol_ids"
}

Status of a send-only tenant

Check the registration status shows the Peppol ID of a send-only tenant as not published:

{
  "peppol_id": "0208:1018265814",
  "state": "not_registered",
  "smp": {
    "service_group": null,
    "business_card": null,
    "document_types": null
  },
  "last_checked_at": "2026-04-16T10:00:00.000000",
  "verified": false,
  "publications": [
    {
      "peppol_id": "0208:1018265814",
      "state": "not_published",
      "latest_event": null,
      "source": null,
      "detail": null,
      "observed_at": null
    }
  ]
}

state is other when the Peppol ID is registered at a different access point.

Become a receiver later

Call Register on Peppol when the tenant is ready to receive documents. No tenant change is necessary.

Testing

Use the organisation API key of a test-mode organisation to test your integration. Send an email to support@e-invoice.be to get this key. You cannot set test mode on a tenant yourself. Each tenant that you create with this key is a test-mode tenant: its sends go to email, and no Peppol traffic occurs. See Test mode and sandbox companies. Set company_email on each test-mode tenant. Without it, each send of the tenant fails with 400 Bad Request. See Contact email address of a test-mode tenant. The Peppol registration operations return 403 Forbidden for a test-mode organisation. See Peppol registration.

Simulate an inbound document

Put a UBL document in the inbox of a test-mode tenant, as if it was received through Peppol. The API creates the document in the RECEIVED state and sends the document.received webhook event to the webhooks of the tenant.

curl -X POST "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r1t/simulate-inbound" \
     -H "Authorization: Bearer $E_INVOICE_ORG_API_KEY" \
     -F "ubl_file=@invoice.xml"

file

required

UBL invoice or credit note as an XML file. The request is multipart/form-data; a raw XML request body is not accepted. The maximum size is 25 MB.

The response has the status 201 Created:

{
  "document_id": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "state": "RECEIVED"
}

Status	Cause
`400 Bad Request`	The file is empty, or the tenant is not in test mode.
`413 Request Entity Too Large`	The file is larger than 25 MB.

The API reads the sender and receiver Peppol IDs, the document type and the line items from the UBL. It does not change the receiver Peppol ID to the Peppol ID of the tenant. The API does not validate the file. It also returns 201 Created and creates a RECEIVED document for an XML file that is not an invoice or a credit note. It does the same for a file that is not XML. Read the result with GET /api/documents/{document_id} and the tenant API key. For the procedure in the app and for the tenant-side view, see Testing received documents and Receive documents.

Onboarding example

The script below creates a tenant, creates an API key and registers the tenant on Peppol. Remove the registration step for a send-only tenant.

Complete onboarding script (Node.js and Python)

const BASE_URL = 'https://api.e-invoice.be';

async function admin(method, path, body) {
  const response = await fetch(`${BASE_URL}${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.E_INVOICE_ORG_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!response.ok) {
    throw new Error(`${method} ${path}: ${response.status} ${await response.text()}`);
  }
  return response.status === 204 ? null : response.json();
}

async function onboardCustomer(customer) {
  // 1. Create the tenant with its Peppol ID.
  const tenant = await admin('POST', '/api/admin/tenants', {
    name: customer.slug,
    description: customer.companyName,
    company_name: customer.companyName,
    company_number: customer.companyNumber,
    company_tax_id: customer.vatNumber,
    company_country: customer.country,
    company_email: customer.email,
    peppol_ids: [customer.peppolId],
  });

  // 2. Create an API key. The id is the bearer token of the tenant.
  const apiKey = await admin('POST', `/api/admin/tenants/${tenant.id}/api-keys`, {
    name: 'production-key',
  });

  // 3. Register on Peppol, so that the tenant can receive documents.
  const registration = await admin(
    'POST',
    `/api/admin/tenants/${tenant.id}/peppol/register`,
    { peppol_id: customer.peppolId },
  );

  return {
    tenantId: tenant.id,
    apiKey: apiKey.id,
    registered: registration.success,
  };
}

const result = await onboardCustomer({
  slug: 'e-invoice-bv',
  companyName: 'E-INVOICE BV',
  companyNumber: '1018265814',
  vatNumber: 'BE1018265814',
  country: 'BE',
  email: 'info@e-invoice.be',
  peppolId: '0208:1018265814',
});

console.log('Tenant:', result.tenantId, 'registered:', result.registered);

import os

import requests

BASE_URL = "https://api.e-invoice.be"
HEADERS = {"Authorization": f"Bearer {os.environ['E_INVOICE_ORG_API_KEY']}"}


def admin(method, path, body=None):
    response = requests.request(
        method, f"{BASE_URL}{path}", headers=HEADERS, json=body, timeout=60
    )
    response.raise_for_status()
    return None if response.status_code == 204 else response.json()


def onboard_customer(customer):
    # 1. Create the tenant with its Peppol ID.
    tenant = admin(
        "POST",
        "/api/admin/tenants",
        {
            "name": customer["slug"],
            "description": customer["company_name"],
            "company_name": customer["company_name"],
            "company_number": customer["company_number"],
            "company_tax_id": customer["vat_number"],
            "company_country": customer["country"],
            "company_email": customer["email"],
            "peppol_ids": [customer["peppol_id"]],
        },
    )

    # 2. Create an API key. The id is the bearer token of the tenant.
    api_key = admin(
        "POST",
        f"/api/admin/tenants/{tenant['id']}/api-keys",
        {"name": "production-key"},
    )

    # 3. Register on Peppol, so that the tenant can receive documents.
    registration = admin(
        "POST",
        f"/api/admin/tenants/{tenant['id']}/peppol/register",
        {"peppol_id": customer["peppol_id"]},
    )

    return {
        "tenant_id": tenant["id"],
        "api_key": api_key["id"],
        "registered": registration["success"],
    }


result = onboard_customer(
    {
        "slug": "e-invoice-bv",
        "company_name": "E-INVOICE BV",
        "company_number": "1018265814",
        "vat_number": "BE1018265814",
        "country": "BE",
        "email": "info@e-invoice.be",
        "peppol_id": "0208:1018265814",
    }
)

print("Tenant:", result["tenant_id"], "registered:", result["registered"])

Errors

The Admin API returns errors as JSON with a detail field. For the general error model, see Errors and troubleshooting.

Status	`detail` (example)	Cause and solution
`401 Unauthorized`	`Admin authentication required`	The request has no `Authorization` header.
`400 Bad Request`	`Tenant does not have a Peppol ID`	The Peppol operations need a Peppol ID in the `peppol_ids` of the tenant. Other `400` causes: an incorrect Peppol ID or a scheme that is not supported (see Supported schemes), an empty file or a tenant that is not in test mode in Simulate an inbound document.
`401 Unauthorized`	`Invalid admin authentication`	The key is not an organisation API key. Make sure that you do not send a tenant API key.
`403 Forbidden`	`Peppol operations are not available for organizations in test mode. Please contact support to enable production mode.`	The organisation is in test mode. The Peppol operations are not available.
`403 Forbidden`	`This Peppol ID does not belong to this tenant.`	The Peppol ID in the request body is not in the `peppol_ids` of the tenant.
`404 Not Found`	`Tenant with ID ten-... not found`	The tenant does not exist or is a tenant of a different organisation. For the list, create and latest API key operations, the Peppol operations and Simulate inbound: also when the tenant is deleted.
`409 Conflict`	`Tenant with name 'e-invoice-bv' already exists`	Use a different tenant name, or find the existing tenant with List tenants.
`409 Conflict`	`API key with name 'production-key' already exists for this tenant`	An active API key of the tenant has this name. Use a different name.
`409 Conflict`	Text that describes the conflict	Register on Peppol: the Peppol ID is active at a different access point.
`413 Request Entity Too Large`	`Uploaded UBL payload exceeds 25 MB limit`	Simulate an inbound document: the file is larger than 25 MB.
`422 Unprocessable Entity`	Array of validation errors	A mandatory field is missing, a field has an incorrect type, or a field value is not permitted (for example `company_tax_id` or `route_override`).
`502 Bad Gateway`	`External service failed: ...` or `SMP service failed: ...`	The SMP failed during a Peppol operation. Try again later.

Example of a 422 response:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "name"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

Best practices

Keep keys secure

The id of an API key is the bearer token. Keep it secret from the moment that you receive it.
Do not write organisation API keys or tenant API keys to logs.
Store tenant API keys encrypted.
Give keys to customers only through a secure channel.
Rotate keys at regular intervals. See Rotate an API key.

Use a naming convention for tenants

Use tenant names that you can calculate from your own data, for example cust-<your customer ID> or a slug of the company name. The API refuses a second active tenant with the same name (409 Conflict), which helps you to prevent duplicates.

Make onboarding safe to repeat

If Create a tenant returns 409 Conflict, the tenant exists. Get it from List tenants and continue with the next step. Register on Peppol and Unregister from Peppol are idempotent, so you can repeat them after a network error.

Keep an audit log

Record each admin operation in your system: the operation, the tenant ID, the user and the time. Do not record API keys.

Check before you register

Validate the Peppol ID in your system, then call Register on Peppol with "dry_run": true. Do the real registration only when the dry run is successful.

Rate limits

The Admin API endpoints have no rate limit at this time. The document write and validation endpoints that a tenant calls with its own API key have a rate limit for each API key. See Errors and troubleshooting.

Support

For access to the Admin API or for technical questions, send an email to support@e-invoice.be.

Next Steps

Reseller programme

Learn how to become a reseller and get an organisation API key.

Create e-invoices

Send documents with the API key of a tenant.

Test mode and sandbox companies

Test mode, sandbox companies and simulated inbound documents.

Usage statistics and credits

Read the usage of a tenant with its API key.

​Overview

​Endpoint overview

​Authentication

​Health check

​Tenant management

​List tenants

​Create a tenant

​Request fields

​Contact email address of a test-mode tenant

​Tenant response fields

​Company number and tax ID

​Why you set the Peppol ID when you create the tenant

​Get a tenant

​Update a tenant

​Delete a tenant

​Plans and credits

​API key management

​Create an API key

​List API keys

​Get the latest API key

​Get one API key

​Update an API key

​Revoke an API key

​Rotate an API key

​Peppol registration

​Check the registration status

​Verify a registration

​Register on Peppol

​Dry run

​Supported schemes

​Update the business card

​Unregister from Peppol

​Send-only tenants

​Create a send-only tenant

​What a send-only tenant can do

​Status of a send-only tenant

​Become a receiver later

​Testing

​Simulate an inbound document

​Onboarding example

​Errors

​Best practices

​Rate limits

​Support

​Next Steps

Reseller programme

Create e-invoices

Test mode and sandbox companies

Usage statistics and credits

Overview

Endpoint overview

Authentication

Health check

Tenant management

List tenants

Create a tenant

Request fields

Contact email address of a test-mode tenant

Tenant response fields

Company number and tax ID

Why you set the Peppol ID when you create the tenant

Get a tenant

Update a tenant

Delete a tenant

Plans and credits

API key management

Create an API key

List API keys

Get the latest API key

Get one API key

Update an API key

Revoke an API key

Rotate an API key

Peppol registration

Check the registration status

Verify a registration

Register on Peppol

Dry run

Supported schemes

Update the business card

Unregister from Peppol

Send-only tenants

Create a send-only tenant

What a send-only tenant can do

Status of a send-only tenant

Become a receiver later

Testing

Simulate an inbound document

Onboarding example

Errors

Best practices

Rate limits

Support

Next Steps