API reference - e-invoice.be

Overview

With the e-invoice.be API you create, send and receive Peppol invoices and credit notes. The API converts each document to UBL BIS Billing 3.0 and transmits it on the Peppol network. This page is an overview. The endpoint pages in this tab give the parameters and the schemas of each operation. For the changes to the API and to this documentation, see the Changelog.

Base URL

There is one API host:

https://api.e-invoice.be

Develop and test with a sandbox company. A sandbox company runs in test mode: the API sends each document as UBL XML to the contact email address of the company, and nothing goes to the Peppol network. The API host and the endpoints are the same as for a production company. See Test mode and sandbox companies.

The contact email address is the company_email field of the company. GET /api/me/ returns it. If company_email is empty, the send call of a sandbox company returns 400 with the detail Tenant is in test mode but no company email is set. See Send errors.

Authentication

Send the API key of your company as a bearer token in the Authorization header:

curl "https://api.e-invoice.be/api/me/" \
  -H "Authorization: Bearer $E_INVOICE_API_KEY"

Three lookup endpoints accept requests without an API key. See Authentication.

Endpoints

Documents

Endpoint	Function
`POST /api/documents/`	Create a document from JSON. The document gets the state `DRAFT`.
`POST /api/documents/ubl`	Create a document from a UBL XML file.
`POST /api/documents/pdf`	Extract the document JSON (and the UBL XML, when possible) from a PDF file. This endpoint does not store a document. To store it, send the JSON to `POST /api/documents/`.
`GET /api/documents/{document_id}`	Get a document.
`DELETE /api/documents/{document_id}`	Delete a document (state `DRAFT` or `FAILED` only). See Delete a draft.
`POST /api/documents/{document_id}/validate`	Validate a stored document.
`POST /api/documents/{document_id}/send`	Send a document. A production company sends it through Peppol. A sandbox company sends it by email to its contact email address.
`GET /api/documents/{document_id}/ubl`	Get the metadata of the UBL XML of a document. Download the XML from the `signed_url` in the response.
`GET /api/documents/{document_id}/timeline`	Get the events of a document.

Schemas: Document schema, LineItem schema. Guides: Create e-invoices, Create credit notes, Self-billing and debit notes, Advanced invoicing, Send UBL documents, Create documents from PDF, Document lifecycle and delivery tracking.

Attachments

Endpoint	Function
`GET /api/documents/{document_id}/attachments`	List the attachments of a document.
`GET /api/documents/{document_id}/attachments/{attachment_id}`	Get one attachment.
`DELETE /api/documents/{document_id}/attachments/{attachment_id}`	Delete one attachment.
`POST /api/documents/{document_id}/attachments`	Add an attachment. Deprecated: put the attachments in the `attachments` field when you create the document.

Guide: Attachments and PDF.

Document lists

Endpoint	Function
`GET /api/inbox/`	List received documents.
`GET /api/inbox/invoices`	List received invoices.
`GET /api/inbox/credit-notes`	List received credit notes.
`GET /api/outbox/`	List sent documents.
`GET /api/drafts/`	List draft documents.
`GET /api/outbox/drafts`	List draft documents. Deprecated: use `GET /api/drafts/`.

Guides: Receive documents for requests, responses, inbox filters and the pattern to prevent double processing. List, filter and manage documents for filters, sort options and drafts.

Mailbox

Endpoint	Function
`GET /api/mailbox/`	List inbound emails.
`GET /api/mailbox/{inbound_email_id}`	Get one inbound email.
`GET /api/mailbox/{inbound_email_id}/attachments/{filename}`	Download an attachment of an inbound email.
`POST /api/mailbox/{inbound_email_id}/reprocess`	Process a failed inbound email again.

Guide: Send invoices by email (Mailbox).

Validation

Endpoint	Function
`POST /api/validate/json`	Validate invoice JSON.
`POST /api/validate/ubl`	Validate a UBL XML file.
`GET /api/validate/peppol-id`	Find out if a Peppol ID is registered on the network.

Validation is not a separate mandatory call. POST /api/documents/ rejects a payload that does not pass the same rules. Use POST /api/validate/json while you develop, because it returns all rule failures and the generated UBL.

Guides: Validation during development, Look up Peppol participants.

Lookup

Endpoint	Function
`GET /api/lookup`	Get the details of a Peppol participant.
`GET /api/lookup/participants`	Search for participants in the Peppol Directory.

Guide: Look up Peppol participants.

PDF conversion

Endpoint	Function
`POST /api/conversion/pdf`	Start the conversion of a PDF file.
`GET /api/conversion/pdf/{task_id}`	Get the status of a conversion.
`GET /api/conversion/pdf/{task_id}/result`	Get the result of a conversion.

Guide: Create documents from PDF.

Webhooks

Endpoint	Function
`GET /api/webhooks/`	List the webhooks.
`POST /api/webhooks/`	Create a webhook.
`GET /api/webhooks/{webhook_id}`	Get a webhook.
`PUT /api/webhooks/{webhook_id}`	Update a webhook.
`DELETE /api/webhooks/{webhook_id}`	Delete a webhook.
`GET /api/webhooks/{webhook_id}/history`	Get the delivery history of a webhook.
`POST /api/webhooks/{webhook_id}/test`	Send a test event to a webhook.

Guide: Webhooks.

Account and usage

Endpoint	Function
`GET /api/me/`	Get the data of the company that owns the API key.
`GET /api/stats`	Get the usage statistics of the company.

Guides: Authentication, Usage statistics and credits.

Admin API for resellers

Resellers that manage more than one customer company use a separate Admin API. It requires an organisation API key and is available to approved resellers only. The Admin API endpoints are not in the OpenAPI specification. In the Admin API, the name of a company is “tenant”. With the Admin API you can:

Create and manage the companies of your customers
Create and rotate the API keys of these companies
Register these companies on the Peppol network

Admin API

Manage the companies of your customers as a reseller

Request and response format

Request format

Requests with a body use JSON, with the header Content-Type: application/json. The endpoints that accept files (POST /api/documents/ubl, POST /api/documents/pdf, POST /api/validate/ubl, POST /api/conversion/pdf) use multipart/form-data.

curl -X POST "https://api.e-invoice.be/api/documents/" \
  -H "Authorization: Bearer $E_INVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "document_type": "INVOICE",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email": "billing@e-invoice.be",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Professional services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "subtotal": 1000.00,
  "total_tax": 210.00,
  "invoice_total": 1210.00,
  "amount_due": 1210.00,
  "payment_term": "Payment within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2026-001"
    }
  ]
}'

const invoice = {
  document_type: "INVOICE",
  invoice_id: "INV-2026-001",
  invoice_date: "2026-10-01",
  due_date: "2026-10-31",
  currency: "EUR",
  purchase_order: "PO-12345",
  vendor_name: "E-INVOICE BV",
  vendor_tax_id: "BE1018265814",
  vendor_address: "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  vendor_email: "billing@e-invoice.be",
  customer_name: "OpenPeppol VZW",
  customer_tax_id: "BE0848934496",
  customer_address: "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  items: [
    {
      description: "Professional services",
      quantity: 10,
      unit: "C62",
      unit_price: 100.00,
      amount: 1000.00,
      tax_rate: "21.00"
    }
  ],
  subtotal: 1000.00,
  total_tax: 210.00,
  invoice_total: 1210.00,
  amount_due: 1210.00,
  payment_term: "Payment within 30 days",
  payment_details: [
    {
      iban: "BE68539007547034",
      swift: "GEBABEBB",
      payment_reference: "INV-2026-001"
    }
  ]
};

const response = await fetch("https://api.e-invoice.be/api/documents/", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(invoice),
});

const result = await response.json();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${JSON.stringify(result)}`);
}
console.log(result);

import os

import requests

invoice = {
  "document_type": "INVOICE",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email": "billing@e-invoice.be",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Professional services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "subtotal": 1000.00,
  "total_tax": 210.00,
  "invoice_total": 1210.00,
  "amount_due": 1210.00,
  "payment_term": "Payment within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2026-001"
    }
  ]
}

response = requests.post(
    "https://api.e-invoice.be/api/documents/",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"},
    json=invoice,
    timeout=30,
)
if not response.ok:
    raise SystemExit(f"HTTP {response.status_code}: {response.text}")
print(response.json())

<?php
$invoice = [
  "document_type" => "INVOICE",
  "invoice_id" => "INV-2026-001",
  "invoice_date" => "2026-10-01",
  "due_date" => "2026-10-31",
  "currency" => "EUR",
  "purchase_order" => "PO-12345",
  "vendor_name" => "E-INVOICE BV",
  "vendor_tax_id" => "BE1018265814",
  "vendor_address" => "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email" => "billing@e-invoice.be",
  "customer_name" => "OpenPeppol VZW",
  "customer_tax_id" => "BE0848934496",
  "customer_address" => "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items" => [
    [
      "description" => "Professional services",
      "quantity" => 10,
      "unit" => "C62",
      "unit_price" => 100.00,
      "amount" => 1000.00,
      "tax_rate" => "21.00"
    ]
  ],
  "subtotal" => 1000.00,
  "total_tax" => 210.00,
  "invoice_total" => 1210.00,
  "amount_due" => 1210.00,
  "payment_term" => "Payment within 30 days",
  "payment_details" => [
    [
      "iban" => "BE68539007547034",
      "swift" => "GEBABEBB",
      "payment_reference" => "INV-2026-001"
    ]
  ]
];

$ch = curl_init("https://api.e-invoice.be/api/documents/");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("E_INVOICE_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($invoice),
]);

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

if ($status >= 400) {
    throw new RuntimeException("HTTP $status: $body");
}
print_r(json_decode($body, true));

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

var invoice = """
{
  "document_type": "INVOICE",
  "invoice_id": "INV-2026-001",
  "invoice_date": "2026-10-01",
  "due_date": "2026-10-31",
  "currency": "EUR",
  "purchase_order": "PO-12345",
  "vendor_name": "E-INVOICE BV",
  "vendor_tax_id": "BE1018265814",
  "vendor_address": "Brusselsesteenweg 119/A, 1980 Zemst, BE",
  "vendor_email": "billing@e-invoice.be",
  "customer_name": "OpenPeppol VZW",
  "customer_tax_id": "BE0848934496",
  "customer_address": "Robert Schumanplein 6 bus 5, 1040 Brussel, BE",
  "items": [
    {
      "description": "Professional services",
      "quantity": 10,
      "unit": "C62",
      "unit_price": 100.00,
      "amount": 1000.00,
      "tax_rate": "21.00"
    }
  ],
  "subtotal": 1000.00,
  "total_tax": 210.00,
  "invoice_total": 1210.00,
  "amount_due": 1210.00,
  "payment_term": "Payment within 30 days",
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "swift": "GEBABEBB",
      "payment_reference": "INV-2026-001"
    }
  ]
}
""";

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

var response = await client.PostAsync(
    "/api/documents/",
    new StringContent(invoice, Encoding.UTF8, "application/json"));

var body = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException($"HTTP {(int)response.StatusCode}: {body}");
}
Console.WriteLine(body);

The API rejects a document whose vendor is not a Peppol ID of your company (406). Before you run this example, replace the vendor fields with those of your own company.

Response format

A successful request returns JSON with a 2xx status code. This example shows the first fields of the response to a create request:

{
  "id": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "created_at": "2026-10-01T10:00:00Z",
  "document_type": "INVOICE",
  "state": "DRAFT",
  "direction": "OUTBOUND",
  "invoice_id": "INV-2026-001"
}

For all fields, see the Document schema.

Error responses

The API returns these error status codes: 400, 401, 403 (Admin API only), 404, 405, 406, 409, 415, 422, 429, 500.

406 means that the document does not obey a business rule, or that its Peppol sender (the vendor, or the customer for self-billing) is not a Peppol ID of your company.
405 means that the document is not in a state that permits a send.
409 means that the sender of a send call is not a Peppol ID of your company.
422 means that the request does not agree with the schema of the endpoint, or that the API cannot read an input file.

Most errors have this body:

{
  "detail": "Document not found"
}

For the body formats, the cause of each code and the retry rules, see Errors and troubleshooting.

Pagination

The document list endpoints (/api/inbox/, /api/outbox/, /api/drafts/) use page (default 1) and page_size (default 20, maximum 100). The response contains items, total, page, page_size, pages and has_next_page. For filters, sort options and a loop sample, see List, filter and manage documents.

The Admin API list endpoints (/api/admin/tenants and its API-key routes) use skip and limit parameters. See the Admin API.

Rate limiting

The API applies a rate limit for each API key to these endpoints:

POST /api/documents/ and POST /api/documents/ubl
POST /api/validate/json and POST /api/validate/ubl

Each of these endpoints has its own counter. When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header. The value of Retry-After is a fixed number of seconds: the length of the rate-limit window. It is not the time until your counter resets. If the request after the wait also gets 429, wait longer before the next attempt. Do not write a fixed limit into your code. A successful response of these endpoints contains these headers:

X-RateLimit-Limit: the number of requests in one window.
X-RateLimit-Remaining: the number of requests that remain in the current window.
X-RateLimit-Reset: the Unix time in seconds when the window ends.

See Rate limits.

Document states

State	Meaning
`DRAFT`	The document exists but is not sent. `POST /api/documents/` always creates a document in this state.
`TRANSIT`	The send request is accepted and the transmission is in progress.
`SENT`	The transmission is complete.
`FAILED`	The transmission failed. You can send the document again.
`RECEIVED`	The document came in from another Peppol participant.

You can send a document only when it is in the DRAFT or FAILED state. For the transitions, the retry behaviour and the webhook events of each state, see Document lifecycle and delivery tracking. To follow the state changes, use webhooks or the timeline. See Document lifecycle and delivery tracking for the state diagrams, the transitions and the timeline.

Supported currencies

The currency field accepts these ISO 4217 codes: EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, CNY, INR, SEK, NOK, DKK, SGD, HKD The default is EUR.

Peppol participant IDs

A Peppol ID has the format scheme:identifier. For example, a Belgian company uses the scheme 0208 with its enterprise number: 0208:1018265814. For the list of schemes and for the lookup of a participant, see Look up Peppol participants.

OpenAPI specification

The reference is generated from the openapi.json file in the docs repository, which a CI check compares with the live spec at https://api.e-invoice.be/api/openapi.json. You can use the live specification to:

Generate a client library in your programming language
Import the API into a test tool (for example Postman or Insomnia)
Validate request and response structures

SDKs and a command-line tool are available: see SDKs and peppol CLI. To connect an AI assistant to your company through MCP, see Model Context Protocol (MCP).

Support

Send an email to the support team

GitHub

See the open-source projects

Next Steps

Quickstart

Send a first invoice with a sandbox company

Authentication

Get and use an API key

Create e-invoices

Create and send an e-invoice

Validation during development

Validate invoices while you develop

​Overview

​Base URL

​Authentication

​Endpoints

​Documents

​Attachments

​Document lists

​Mailbox

​Validation

​Lookup

​PDF conversion

​Webhooks

​Account and usage

​Admin API for resellers

Admin API

​Request and response format

​Request format

​Response format

​Error responses

​Pagination

​Rate limiting

​Document states

​Supported currencies

​Peppol participant IDs

​OpenAPI specification

​Support

Support

GitHub

​Next Steps

Quickstart

Authentication

Create e-invoices

Validation during development

Overview

Base URL

Authentication

Endpoints

Documents

Attachments

Document lists

Mailbox

Validation

Lookup

PDF conversion

Webhooks

Account and usage

Admin API for resellers

Request and response format

Request format

Response format

Error responses

Pagination

Rate limiting

Document states

Supported currencies

Peppol participant IDs

OpenAPI specification

Support

Next Steps