Overview
When a supplier sends an invoice or a credit note to your Peppol ID, e-invoice.be receives the document, stores it, and puts it in the inbox of your company. This guide shows how to find new documents, how to read their data, and how to download the original UBL file, the PDF and the other attachments. A received document hasdirection: "INBOUND" and state: "RECEIVED".
Prerequisites
- An API key for the company that receives the documents. See Authentication.
- A production company must be registered as a receiver on the Peppol network. Without this registration, senders cannot find your Peppol ID and no document arrives.
- A sandbox company does not receive documents from the Peppol network. Use Simulate inbound to put documents in its inbox. See Test with a sandbox company.
How a document arrives
e-invoice.be receives the document
The UBL and its attachments are stored
A PDF is made if the sender did not supply one
{document_id}.pdf. For example, the document doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d gets the file doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.pdf. If the PDF generation fails, the document is received, but it has no PDF.Exception: a document can arrive through the French route as a PDF file (Factur-X). Then that original PDF is the PDF of the document, and e-invoice.be generates no PDF. The file name of the original starts with original-. This route applies only to a French company that is enrolled for it.The document goes to the RECEIVED state
The webhook is sent
document.received gets an event with the document_id.Find new documents
There are two methods to find new documents: webhooks and polling. Webhooks are the recommended method. Polling is a good safety net in addition to webhooks.Webhook (recommended)
Create a webhook that subscribes todocument.received. e-invoice.be calls your URL when a document is in the RECEIVED state. Webhooks gives the setup procedure and the signature verification.
document_id. Use this ID to get the document.
document.received.failed tells you that e-invoice.be could not process an incoming document. The data object has the same shape. Such a document is not in the RECEIVED state, thus GET /api/inbox/ does not list it. Not all receive failures give this event.Polling
CallGET /api/inbox/ at a fixed interval. The default sort is created_at in descending order, thus the newest documents are on the first page.
GET /api/documents/{document_id}. In the list, a field without a value is present with the value null. The single-document response omits such fields. The example shows only some of the fields.
has_next_page is true.
Prevent double processing
Because the API does not record what you have processed, keep this record in your own system. Use one of these patterns, or the two together.Set of processed document IDs
Set of processed document IDs
id of each document after you process it. Before you process a document, look for its id in your store and skip the document if the id is there.This pattern is correct for webhooks and for polling. Use it in each webhook handler, so that a repeated event does not process the same document twice.Cursor on created_at
Cursor on created_at
created_at value of the newest document that you processed, and the id of each processed document with that same created_at. At each poll, read the inbox with sort_by=created_at and sort_order=desc, page by page. Stop when you find a document whose created_at is earlier than the stored value. Skip a document whose created_at is equal to the stored value and whose id is in the stored list. Process the documents that you collected from the oldest to the newest, then store the new cursor.Example cursor: {"created_at": "2026-10-01T09:15:42.118000Z", "processed_ids": ["doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"]}.date_from and date_to filter on the issue date of the invoice (invoice_date), not on the time of receipt. Do not use them as a cursor: a supplier can send an invoice with an issue date in the past.Complete polling example (Node.js and Python)
Complete polling example (Node.js and Python)
Get the document
GET /api/documents/{document_id} returns the data of the document as JSON. This is the same endpoint and the same schema as for the documents that you send. See the Document schema.
note, thus the response has no note key. The same document in GET /api/inbox/ has "note": null.
A field with a default value is always in the response. For example, currency (default EUR) and tax_code (default S) are always present.
The API returns decimal values as strings. In a line item, quantity and unit_price have 4 decimals ("10.0000"), and amount, tax and tax_rate have 2 decimals ("1000.00"). price_base_quantity has no trailing zeros ("1", "100"). Compare amounts as numbers, not as strings.
In a line item of a received document, name is the item name of the UBL (cbc:Name). description is the item description of the UBL. If the UBL has no item description, description has the same value as name, as in the example above.
These fields are the most important for a received document:
SELFBILLING_INVOICE or SELFBILLING_CREDIT_NOTE. In a self-billing document, the buyer issues the invoice in the name of the supplier, thus your company is the vendor on the document and not the customer. See Self-billing and debit notes.Download the original UBL
The JSON data is a conversion of the UBL. Keep the original UBL XML for your archive: it is the legal document that the sender transmitted.GET /api/documents/{document_id}/ubl returns the metadata of the UBL file and a signed URL for the download.
validated_at is present when the UBL was validated. The signed_url is valid for 1 hour. For the description of each field, see Download the UBL.
Download the attachments and the PDF
A received document can have attachments: the PDF of the invoice and the other files that the sender embedded in the UBL (for example a timesheet or a delivery note). If the sender embedded no PDF, the list contains the PDF that e-invoice.be generated, with the file name{document_id}.pdf. For the exception of the French route, see How a document arrives.
List the attachments
GET /api/documents/{document_id}/attachments returns all attachments of the document. Each item has a file_url that you can download immediately.
404 Not Found with "detail": "Document attachments not found" when the document has no attachments. Treat this response as an empty list.Get one attachment
GET /api/documents/{document_id}/attachments/{attachment_id} returns one attachment with a new file_url. Use this call when you stored the attachment ID and you need the file again later.
404 Not Found with "detail": "Document attachment not found". See also Download one attachment.
To find the PDF of the invoice, select the attachment with file_type equal to application/pdf. A sender can embed more than one PDF; in that case use file_name to identify the correct file. If no attachment has the type application/pdf (or the call returns 404), the document has no PDF. Use the UBL file as the source.
See Attachments and PDF for the permitted file types and for the procedure to add attachments to the documents that you send.
Filter the inbox
GET /api/inbox/ returns the documents with direction: "INBOUND" and state: "RECEIVED". It accepts the parameters in this table. All parameters are optional, and you can combine them.
date_fromanddate_tofilter on the issue date of the invoice (invoice_date), not on the time of receipt.- The API uses only the date part of
date_fromanddate_to, and both limits are inclusive. For example,date_to=2026-10-31T00:00:00includes the invoices with the issue date 31 October 2026. senderfinds a text invendor_name,vendor_email,vendor_tax_idorvendor_company_id.- Received documents do not get the type
DEBIT_NOTE, thustype=DEBIT_NOTEreturns an empty list.
Shortcut endpoints
Two endpoints return one document type only. They acceptpage, page_size, sort_by and sort_order, and return the same paginated response. They do not accept sender, date_from, date_to or search; use GET /api/inbox/ with the type parameter when you need these filters.
RECEIVED state, and also inbound documents in the TRANSIT state (the processing is not complete) or the FAILED state (the processing failed). Check state in each item, or use GET /api/inbox/?type=INVOICE to get only RECEIVED documents.
Test with a sandbox company
A sandbox company gets no documents from the Peppol network. Use Simulate inbound to put a document in its inbox:Open the inbox of the sandbox company
Simulate an inbound document
Run your integration
RECEIVED state, GET /api/inbox/ lists it, and the document.received webhooks of the company are sent. All samples on this page operate on this document with the API key of the sandbox company.Frequently asked questions
Can I mark a document as read or processed?
Can I mark a document as read or processed?
id as the key. See Prevent double processing.Must I poll if I use webhooks?
Must I poll if I use webhooks?
How long are the download URLs valid?
How long are the download URLs valid?
signed_url (UBL) and file_url (attachments) are valid for 1 hour. Each call to the endpoint returns a new URL.Why is my inbox empty?
Why is my inbox empty?
Which document types can I receive?
Which document types can I receive?
INVOICE, CREDIT_NOTE, SELFBILLING_INVOICE or SELFBILLING_CREDIT_NOTE. The type comes from the UBL document (Invoice or CreditNote) and its self-billing marker. Use the type parameter of GET /api/inbox/ to get one type.