Skip to main content
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
  • get the usage statistics of all tenants in one request
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.

Authentication

Send the organisation API key as a bearer token. A tenant API key does not give access to the Admin API.
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.

Tenant management

List tenants

Get the tenants of your organisation, newest first. Deleted tenants are not in the list.
integer
default:"0"
Number of tenants to skip.
integer
default:"100"
Maximum number of tenants to return.
total is the number of tenants that are not deleted, not the number of tenants in this page. For example, an organisation with five tenants that are not deleted and the request ?skip=0&limit=2 gives two entries in tenants and "total": 5.

Create a tenant

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 API removes spaces at the start and the end of each ID and changes letters to lower case: 9938:LU25790269 becomes 9938:lu25790269. 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. For example, FR selects the French route fr-superpdp, but France gives the default route peppol-direct. The API does not report an error for France.
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:
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:
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:
1

Set the contact email address

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

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
Legacy field. It does not show if a Peppol ID is published on the SMP (Service Metadata Publisher) of e-invoice.be. It is usually false, also for a tenant with a published Peppol ID. To get the registration status, use Check the registration status.
string | null
Legacy field. It does not show if or when a Peppol ID was published.
string | null
Email address of the tenant at outbox.email.e-invoice.be. The create and get operations fill this field. The other operations return null. The local part is a slug of company_name, a + and a key of 32 characters, for example e-invoice-bv+3f9a1c7e5b2d8h4k6m1n9p3q7r2s5t8w@outbox.email.e-invoice.be. If company_name is not set, the slug is einvoice.
string
Activation state of the tenant for its destination network. Some delivery routes need a one-time activation before the first send.
  • not_required: no activation is necessary. The tenant can send immediately. A tenant that sends through Peppol has this value.
  • not_enrolled: activation is necessary, but it has not started. Send an email to support@e-invoice.be to start it.
  • pending: activation has started. The tenant cannot send yet.
  • enrolled: activation is complete. The tenant can send.
  • failed: activation did not complete. status_message gives the reason.
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: 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

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

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: null for plan or credit_balance gives 422 Unprocessable Entity, and null for name makes the request fail. For example, {"company_email": null} clears the contact email address, and {"name": null} fails. To change the name, send a new name. 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.For example, {"route_override": "peppol-direct"} sends the documents of a tenant with "company_country": "FR" through Peppol. {"route_override": null} sets the French route again.
This example adds the contact email address and an IBAN:
The response has the status 200 OK and contains the full tenant:
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.
The response has the status 204 No Content and no body:
A second delete of the same tenant also returns 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 settings in the Admin API. To read the usage of all tenants, see Get the usage statistics of all tenants.
The response is the full tenant with the new values (shortened here):
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

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:

API key response fields

Each API key operation returns these fields. List API keys returns them for each entry of api_keys.
string
The API key: api- and 32 characters, for example api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y. Use it as api_key_id in the paths and as the bearer token of the tenant.
string
Identifier of the tenant of the key, for example ten-9k2m4p7q3w5x8r1t.
string
Name of the key.
string | null
Description of the key. null when no description is set.
string
Date and time when the key was created.
string
Date and time of the last change.
boolean
default:"false"
true when the key is revoked. List API keys and Get the latest API key return only active keys, so there the value is always 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:
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.
integer
default:"0"
Number of API keys to skip.
integer
default:"100"
Maximum number of API keys to return.
total is the number of active API keys of the tenant, not the number of keys in this page. For example, a tenant with three active keys and the request ?limit=1 gives one entry in api_keys and "total": 3.
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.
If the tenant has no active API key, the response is 404 Not Found:

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.
Response for an active key:
Response for a revoked key:
If the key does not exist for this tenant, the response is 404 Not Found:

Update an API key

Change the name or the description of an API key. The id (the bearer token) does not change. Send only the fields that you want to change. The API keeps the value of each field that is not in the request body. {"description": null} clears the description. Do not send null for name: the request then fails. To change the name, send a new name.
string
New name. A name that a different active key of the tenant has gives 409 Conflict.
string
New description.

Revoke an API key

The response has the status 204 No Content and no body:
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. A second revoke of the same key also returns 204 No Content. An api_key_id that is not a key of the tenant gives 404 Not Found, with the same detail as in Get one API key.

Rotate an API key

1

Create a new API key

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

Give the new key to your customer

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

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:

Check the registration status

boolean
default:"false"
Set to true to do a live check on the network. See Verify a registration.
The response has the status 200 OK. smp.document_types has one entry for each default document type that is on the SMP; after a registration, there are six. The lists in smp are shortened here:
string
The Peppol ID that the API checked. This is always the first ID in the peppol_ids of the tenant. state and smp apply only to this ID. For example, with "peppol_ids": ["0208:1018265814", "9925:be1018265814"], the API checks 0208:1018265814.
string
default:"not_registered"
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.
string
Date and time of this status check.
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.
The value of latest_event sets the state of a publication. source is phoss for an event of a registration or an unregistration, and dns for a live check. If the tenant has no Peppol ID, the response is 400 Bad Request:
If the first Peppol ID of the tenant has no colon, for example 02081018265814, the response is also 400 Bad Request:
If the first Peppol ID has no identifier after the colon, for example 0208:, the response is also 400 Bad Request. The detail starts with Peppol ID address cannot be empty.

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.
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):
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". Then detail gives the reason:
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

string
required
Peppol ID to register, in the form scheme:identifier, for example 0208:1018265814 or 9938:lu25790269. The ID must be in the peppol_ids of the tenant; if not, the response is 403 Forbidden. 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:
  1. It checks the form scheme:identifier. Then it checks that the Peppol ID is in the peppol_ids of the tenant. Then it checks the scheme and the format of the identifier.
  2. It looks for the Peppol ID on the network. An ID that is active at a different access point gives 409 Conflict.
  3. It creates the service group on the SMP.
  4. It adds the six default document types: invoice, credit note, self-billing invoice, self-billing credit note, invoice response and message level response.
  5. It adds a business card. For a Belgian Peppol ID, the company data comes from the KBO (Crossroads Bank for Enterprises). For a Peppol ID of a different country, the name on the business card is the company_name of the tenant. If company_name is not set, the API uses the name of the tenant.
The response has the status 200 OK (the company_data object is shortened here):
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 and company_name; the other fields are null. Here company_number is the identifier part of the Peppol ID, not the company_number of the tenant. company_name is the name of the business card. For example, "peppol_id": "9938:lu25790269" gives:

Registration response fields

boolean
true when the service group is on the SMP. A registration that fails returns an error status, not "success": false.
string
The registered Peppol ID, in lower case and with no spaces at the start and the end. For example, 9938:LU25790269 gives 9938:lu25790269.
object
The company data for the business card: company_number, company_name, company_country, company_address, company_zip, company_city, status, juridical_situation, type_of_enterprise, juridical_form, start_date and address_type. Each field is a string or null.
object
The result of the service group step.
object
The result of the business card step.
object
The result of the document type step. The fields are success, message, error, error_type and dry_run, as in business_card. message is Document endpoints added successfully, or DRY RUN: Would add document endpoints in a dry run.
"success": true does not prove that the API added the business card and the document types. Make sure that business_card.success and document_endpoints.success are also true. If one of them is false, read its error and call Register on Peppol again. For a Belgian Peppol ID, a failed KBO lookup gives business_card.success true, but business_card_data is null and the API adds no business card.
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. For example, the tenant has "peppol_ids": ["0208:101826581"], and the request has "peppol_id": "0208:101826581". The identifier has 9 digits instead of 10. The response is 400 Bad Request, and the detail starts with Invalid Peppol ID address for scheme 0208: expected.

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.
The response has the status 200 OK (the company_data object is shortened here):
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. This applies only to a test-mode tenant of a production organisation. For a test-mode organisation, the Peppol operations return 403 Forbidden before this step. For a test-mode tenant, Update the business card returns {"success": true} and Unregister from Peppol returns {"success": true, "warnings": null}. The two operations 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. For the schemes 0208, 0204, 0240 and 0246, the API also calculates the check digits of the identifier. Incorrect check digits give 400 Bad Request. For example, 0204:04011000-1234512345-06 is a correct Leitweg-ID. 0204:04011000-1234512345-07 gives this response:
For Latvia, the unified registration number goes in scheme 0218 and the VAT number goes in scheme 9939. For example, 0218:50203054851 and 9939:lv50203054851 are correct. 0218:lv50203054851 gives 400 Bad Request, because the 0218 identifier accepts only digits. Schemes of other countries (for example Austria, Italy, Estonia 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:
The company data lookup (KBO) is for Belgium only. For a Peppol ID of a different country, the business card gets the company_name of the tenant (or its name) and the country of the scheme. The register request has no field for the company name. Set company_name on the tenant before the registration, or change 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.
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. If you do not send name, or send null, the name on the business card does not change.
The response has the status 200 OK. success is always true; a failed update returns an error status.
The update replaces the card. It writes a new business card with only two values: the name and the country code of the card. The name comes from the request, or from the current card when the request has no name. The VAT identifier, the website, the contact and the geographical information of the card are then removed. This also occurs when you send no name.For example, before the update, Check the registration status gives this smp.business_card.business_entity:
After {"peppol_id": "0208:1018265814", "name": "E-INVOICE BV"}, it gives:
If the Peppol ID has no business card on the SMP, the response is 400 Bad Request:
The response is also 400 Bad Request in these conditions:
  • The tenant has no Peppol ID.
  • The Peppol ID has no colon, or has no identifier after the colon. For example, 0208 and 0208: are not correct.
  • 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.
string
required
Peppol ID to unregister. It must be in the peppol_ids of the tenant; if not, the response is 403 Forbidden.
boolean
Always true in a 200 response. A failed unregistration returns an error status.
string[] | null
Warnings that do not stop the operation. null when there is no warning. The only value is Participant was already unregistered. The API does not put a failed removal of the document types or of the business card in this list.
The operation is idempotent. A Peppol ID that is not on the SMP also gives 200 OK with "success": true. Usually warnings is then null, because the SMP reports no error. If the SMP reports that the participant is not found, the response is:
The Peppol ID must have the form scheme:identifier. 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

1

Create the tenant

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

Create an API key

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

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.
The response has the status 200 OK and contains the document. This example shows the first fields:
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

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:

Status of a send-only tenant

Check the registration status shows the Peppol ID of a send-only tenant as not published:
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.
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:
The API reads the sender and receiver Peppol IDs, the document type and the line items from the UBL. A self-billing UBL gives the type SELFBILLING_INVOICE or SELFBILLING_CREDIT_NOTE. The API stores each embedded attachment of the UBL as an attachment of the document. If the UBL has no PDF attachment, the API makes a PDF from the UBL and adds it. 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.

Usage statistics

Get the usage statistics of all tenants

Get the usage of all tenants of your organisation in one request. The response counts the actions DOCUMENT_SENT and DOCUMENT_RECEIVED for each tenant and for the organisation, for each aggregation period. Use this operation for re-invoicing. You do not need the API key of each tenant.
string
First day of the period, in the format yyyy-mm-dd. If you do not send it, the period starts at the first action of the organisation.
string
Last day of the period, in the format yyyy-mm-dd, for example 2026-10-31. If you do not send it, the period stops at the last action of the organisation. An end_date before start_date gives 400 Bad Request.
string
default:"DAY"
Length of each aggregation period: DAY, WEEK or MONTH. A different value gives 422 Unprocessable Entity.
The response has the status 200 OK:
string
Identifier of your organisation, for example org-4f7k2m9p3q8w5x1z.
string
First day of the period (yyyy-mm-dd).
string
Last day of the period (yyyy-mm-dd).
string
The aggregation that the API used: DAY, WEEK or MONTH.
integer
Number of days in the period. The minimum is 1.
number
Total actions of all tenants, divided by total_days.
object[]
The actions of all tenants together. There is one entry for each aggregation period and each action. Each entry has action (DOCUMENT_SENT or DOCUMENT_RECEIVED), stat_date and count. For WEEK, stat_date is the first day of the week. For MONTH, stat_date is the first day of the month.
object[]
The usage of each tenant, newest tenant first. Each entry has tenant_id, name, test_mode, deleted_at, credit_balance, actions (same entries as totals), average_daily_usage and budget_estimation_days. actions is empty when the tenant has no actions in the period. budget_estimation_days is credit_balance divided by average_daily_usage, and 0.0 when average_daily_usage is 0.
A deleted tenant is in tenants only when it has actions in the period. Its deleted_at then has the date and time of the delete. For an active tenant, deleted_at is null. The API rounds average_daily_usage and budget_estimation_days to one decimal. In totals and in actions, the entries are in date order. For the same date, DOCUMENT_RECEIVED comes before DOCUMENT_SENT. If the organisation has no actions and you send no dates, the period is one day: the current date. total_days is then 1, and each tenant has an empty actions list. For the usage of one tenant with its own API key, see Usage statistics and credits.

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.

Errors

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

Best practices

  • 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 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.
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.
Record each admin operation in your system: the operation, the tenant ID, the user and the time. Do not record API keys.
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.