> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e-invoice.be/llms.txt
> Use this file to discover all available pages before exploring further.
# API reference
> Find the host, the authentication, all endpoints, the response formats and the limits of the e-invoice.be API.
## 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](/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](/environments).
## Authentication
Send the API key of your company as a bearer token in the `Authorization` header:
```bash theme={null}
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](/authentication#endpoints-without-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` | Create a document from a PDF file. |
| `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](/guides/managing-documents#delete-a-draft). |
| `POST /api/documents/{document_id}/validate` | Validate a stored document. |
| `POST /api/documents/{document_id}/send` | Send a document through Peppol. |
| `GET /api/documents/{document_id}/ubl` | Get the UBL XML of a document. |
| `GET /api/documents/{document_id}/timeline` | Get the events of a document. |
Schemas: [Document schema](/api-reference/schemas/document), [LineItem schema](/api-reference/schemas/line-item).
Guides: [Create e-invoices](/guides/creating-invoices), [Create credit notes](/guides/credit-notes), [Self-billing and debit notes](/guides/self-billing), [Advanced invoicing](/guides/advanced-invoicing), [Send UBL documents](/guides/ubl-documents), [Create documents from PDF](/guides/pdf-documents), [Document lifecycle and delivery tracking](/guides/document-lifecycle).
### 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](/guides/attachments).
### 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](/guides/receiving-documents) for requests, responses, inbox filters and the pattern to prevent double processing. [List, filter and manage documents](/guides/managing-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)](/guides/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](/guides/validation), [Look up Peppol participants](/guides/lookup-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](/guides/lookup-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](/guides/pdf-documents).
### 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](/essentials/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](/authentication), [Usage statistics and credits](/guides/usage-statistics).
## 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
Manage the companies of your customers as a reseller
See also the [reseller programme](/reseller-programme).
## 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`.
```bash cURL theme={null}
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"
}
]
}'
```
```javascript Node.js theme={null}
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);
```
```python Python theme={null}
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 PHP theme={null}
"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));
```
```csharp C# theme={null}
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:
```json theme={null}
{
"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](/api-reference/schemas/document).
### Error responses
The API returns these error status codes: `400`, `401`, `403` (Admin API only), `404`, `405`, `406`, `409`, `415`, `422`, `429`, `500`. Most errors have this body:
```json theme={null}
{
"detail": "Document not found"
}
```
For the body formats, the cause of each code and the retry rules, see [Errors and troubleshooting](/guides/errors).
## 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](/guides/managing-documents).
The Admin API list endpoints (`/api/admin/tenants` and its API-key routes) use `skip` and `limit` parameters. See the [Admin API](/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`
When you exceed the limit, the API returns `429 Too Many Requests` with a `Retry-After` header that contains a number of seconds. Do not write a fixed limit into your code. Read `Retry-After` and wait. See [Rate limits](/guides/errors#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](/guides/document-lifecycle).
To follow the state changes, use [webhooks](/essentials/webhooks) or the timeline. See [Document lifecycle and delivery tracking](/guides/document-lifecycle) 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](/guides/lookup-participants#peppol-id-schemes).
## 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](/sdks) and [peppol CLI](/cli). To connect an AI assistant to your company through MCP, see [Model Context Protocol (MCP)](/essentials/mcp).
## Support
Send an email to the support team
See the open-source projects
## Next Steps
Send a first invoice with a sandbox company
Get and use an API key
Create and send an e-invoice
Validate invoices while you develop
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.