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
Endpoint overview
All paths are on the hosthttps://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.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.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
Onlyname is required. All other fields are optional.
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.Plan of the tenant:
starter, pro or enterprise. See Plans and credits.Credit balance of the tenant. See Plans and credits.
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.Company registration number from the national business register, without a country prefix. For Belgium this is the CBE number, for example
1018265814.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.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.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.test_mode (see below). route_override is accepted only by Update a tenant; create ignores it.
The response has the status 201 Created:
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 thecompany_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:
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: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.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.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_messagegives the reason.
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_numberis the registration number from the national business register, without a country prefix (Belgium: CBE number1018265814, Netherlands: KvK number).company_tax_idis the VAT number with the country prefix (BE1018265814,NL123456789B01).
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 inpeppol_ids for three functions:
- Creating and sending.
POST /api/documents/accepts a document only when the sender Peppol ID is in thepeppol_idsof the tenant (if not:406).POST /api/documents/{document_id}/senddoes the same check (if not:409). For a self-billing document, the Peppol sender is the customer, so the check applies to thecustomer_*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
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 valuenull, 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:
nameis optional.route_overrideis accepted. Create ignores this field.test_modeis not accepted. The test mode of a tenant does not change.
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.200 OK and contains the full tenant:
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.204 No Content and no body:
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.
Plans and credits
You set the plan and the credit balance of a tenant with the fieldsplan 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.
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
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.201 Created:
API key response fields
Each API key operation returns these fields. List API keys returns them for each entry ofapi_keys.
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.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.List API keys
Get the active API keys of a tenant, newest first. Revoked keys are not in the list.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.
Get the latest API key
Get the active API key of a tenant that was created last.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, withis_deleted: true.
404 Not Found:
Update an API key
Change the name or the description of an API key. Theid (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.
Revoke an API key
204 No Content and no body:
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.Check the registration status
Set to
true to do a live check on the network. See Verify a registration.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:
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.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.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.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.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:
02081018265814, the response is also 400 Bad Request:
0208:, the response is also 400 Bad Request. The detail starts with Peppol ID address cannot be empty.
Verify a registration
Withoutverify, 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.
verified is true, and each publication shows the result of the live check (the smp object is shortened here):
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
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.Set to
true to do all checks and make no change on the SMP. See Dry run.- It checks the form
scheme:identifier. Then it checks that the Peppol ID is in thepeppol_idsof the tenant. Then 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). For a Peppol ID of a different country, the name on the business card is the
company_nameof the tenant. Ifcompany_nameis not set, the API uses thenameof the tenant.
200 OK (the company_data object is shortened here):
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
true when the service group is on the SMP. A registration that fails returns an error status, not "success": false.The registered Peppol ID, in lower case and with no spaces at the start and the end. For example,
9938:LU25790269 gives 9938:lu25790269.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.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.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.
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.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:
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:
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.Peppol ID of the business card. It must be in the
peppol_ids of the tenant; if not, the response is 403 Forbidden.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.200 OK. success is always true; a failed update returns an error status.
If the Peppol ID has no business card on the SMP, the response is 400 Bad Request:
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,
0208and0208:are not correct. - The scheme is not a supported scheme.
- The identifier does not obey the rules of the scheme.
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.Peppol ID to unregister. It must be in the
peppol_ids of the tenant; if not, the response is 403 Forbidden.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.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:
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 nosend_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 The response has the status
POST /api/documents/ and send it. See Create e-invoices. Do not call the register operation.200 OK and contains the document. This example shows the first fields: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. Setcompany_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 theRECEIVED state and sends the document.received webhook event to the webhooks of the tenant.
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.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 actionsDOCUMENT_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.
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.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.Length of each aggregation period:
DAY, WEEK or MONTH. A different value gives 422 Unprocessable Entity.200 OK:
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.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.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.Complete onboarding script (Node.js and Python)
Complete onboarding script (Node.js and Python)
Errors
The Admin API returns errors as JSON with adetail field. For the general error model, see Errors and troubleshooting.
Example of a
422 response:
Best practices
Keep keys secure
Keep keys secure
- The
idof 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 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
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
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
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.