Receive documents

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 has direction: "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.

Resellers: a send-only tenant has no Peppol registration, thus its inbox stays empty. See Send-only tenants in the Admin API guide.

How a document arrives

e-invoice.be receives the document

The access point receives the Peppol message and finds the company from the receiver Peppol ID.

The UBL and its attachments are stored

The original UBL XML is stored. Each file that the sender embedded in the UBL is extracted and stored as an attachment of the document.

A PDF is made if the sender did not supply one

If the UBL contains no PDF attachment, e-invoice.be generates a PDF from the UBL and adds it as an attachment with the file name {document_id}.pdf.

The document goes to the RECEIVED state

The document data (parties, totals, line items) is available as JSON, and the document is in the inbox.

The webhook is sent

Each webhook of the company that subscribes to 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.

The API has no “mark as processed” endpoint and no “unread” filter. A document stays in the inbox after you read it. Your system must record which documents it has processed. See Prevent double processing.

Webhook (recommended)

Create a webhook that subscribes to document.received. e-invoice.be calls your URL when a document is in the RECEIVED state. Webhooks gives the setup procedure and the signature verification.

{
  "id": "evt-e7wyc7gtpqx4z73x2wqmwhebhbb3r8n3ovfhcsdbulxr3s2awf49de76yglrnri3",
  "tenant_id": "ten-5x7y9z1a3b5c7d9e",
  "created_at": 1790846142,
  "type": "document.received",
  "data": {
    "document_id": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
  }
}

The event contains only the document_id. Use this ID to get the document.

The event 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.

Polling

Call GET /api/inbox/ at a fixed interval. The default sort is created_at in descending order, thus the newest documents are on the first page.

curl -X GET "https://api.e-invoice.be/api/inbox/?sort_by=created_at&sort_order=desc&page=1&page_size=50" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY"

const params = new URLSearchParams({
  sort_by: "created_at",
  sort_order: "desc",
  page: "1",
  page_size: "50",
});

const response = await fetch(`https://api.e-invoice.be/api/inbox/?${params}`, {
  headers: { Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}` },
});

if (!response.ok) {
  throw new Error(`Inbox request failed: ${response.status}`);
}

const inbox = await response.json();
console.log(inbox.total, inbox.items.map((doc) => doc.id));

import os

import requests

response = requests.get(
    "https://api.e-invoice.be/api/inbox/",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"},
    params={
        "sort_by": "created_at",
        "sort_order": "desc",
        "page": 1,
        "page_size": 50,
    },
    timeout=30,
)
response.raise_for_status()

inbox = response.json()
print(inbox["total"], [doc["id"] for doc in inbox["items"]])

<?php
$query = http_build_query([
    'sort_by' => 'created_at',
    'sort_order' => 'desc',
    'page' => 1,
    'page_size' => 50,
]);

$ch = curl_init("https://api.e-invoice.be/api/inbox/?{$query}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('E_INVOICE_API_KEY')],
]);

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

if ($status !== 200) {
    throw new RuntimeException("Inbox request failed: {$status}");
}

$inbox = json_decode($body, true);
echo $inbox['total'] . PHP_EOL;

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

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.GetAsync(
    "/api/inbox/?sort_by=created_at&sort_order=desc&page=1&page_size=50");
response.EnsureSuccessStatusCode();

using var inbox = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
Console.WriteLine(inbox.RootElement.GetProperty("total").GetInt32());

The response is one page of documents. Each item has the same shape as the response of GET /api/documents/{document_id}.

{
  "items": [
    {
      "id": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
      "created_at": "2026-10-01T09:15:42.118Z",
      "document_type": "INVOICE",
      "state": "RECEIVED",
      "direction": "INBOUND",
      "invoice_id": "INV-2026-001",
      "invoice_date": "2026-10-01",
      "due_date": "2026-10-31",
      "currency": "EUR",
      "vendor_name": "E-INVOICE BV",
      "vendor_tax_id": "BE1018265814",
      "customer_name": "OpenPeppol VZW",
      "customer_tax_id": "BE0848934496",
      "subtotal": "1000.00",
      "total_tax": "210.00",
      "invoice_total": "1210.00",
      "amount_due": "1210.00"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 50,
  "pages": 1,
  "has_next_page": false
}

Read the subsequent page while 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

Store the 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

Store the created_at value and the id of the newest document that you processed. At each poll, read the inbox with sort_by=created_at and sort_order=desc, page by page, and stop when you find a document whose created_at is not later than the stored value. Process the documents that you collected from the oldest to the newest, then store the new cursor.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)

These programs read the inbox from the newest document to the stored cursor, download the UBL of each new document, and then move the cursor. The cursor is in a local JSON file; use your database in a production system.

import { readFile, writeFile } from "node:fs/promises";

const BASE_URL = "https://api.e-invoice.be";
const HEADERS = { Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}` };
const CURSOR_FILE = "inbox-cursor.json";

async function api(path) {
  const response = await fetch(`${BASE_URL}${path}`, { headers: HEADERS });
  if (!response.ok) {
    throw new Error(`GET ${path} failed: ${response.status}`);
  }
  return response.json();
}

async function loadCursor() {
  try {
    return JSON.parse(await readFile(CURSOR_FILE, "utf8"));
  } catch {
    return { createdAt: null, processedIds: [] };
  }
}

async function collectNewDocuments(cursor) {
  const documents = [];
  let page = 1;

  while (true) {
    const inbox = await api(
      `/api/inbox/?sort_by=created_at&sort_order=desc&page=${page}&page_size=100`
    );

    for (const doc of inbox.items) {
      if (cursor.createdAt && new Date(doc.created_at) < new Date(cursor.createdAt)) {
        return documents;
      }
      if (!cursor.processedIds.includes(doc.id)) {
        documents.push(doc);
      }
    }

    if (!inbox.has_next_page) {
      return documents;
    }
    page += 1;
  }
}

async function processDocument(doc) {
  const ubl = await api(`/api/documents/${doc.id}/ubl`);
  const download = await fetch(ubl.signed_url);
  if (!download.ok) {
    throw new Error(`UBL download failed: ${download.status}`);
  }
  await writeFile(ubl.file_name, Buffer.from(await download.arrayBuffer()));
  console.log(`Processed ${doc.id} (${doc.document_type} ${doc.invoice_id})`);
}

const cursor = await loadCursor();
const documents = await collectNewDocuments(cursor);

// Oldest first, so that the cursor only moves forward.
for (const doc of documents.reverse()) {
  await processDocument(doc);
  const sameInstant = cursor.createdAt === doc.created_at;
  cursor.processedIds = sameInstant ? [...cursor.processedIds, doc.id] : [doc.id];
  cursor.createdAt = doc.created_at;
  await writeFile(CURSOR_FILE, JSON.stringify(cursor));
}

import json
import os
from datetime import datetime
from pathlib import Path

import requests

BASE_URL = "https://api.e-invoice.be"
HEADERS = {"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"}
CURSOR_FILE = Path("inbox-cursor.json")


def api(path, **params):
    response = requests.get(f"{BASE_URL}{path}", headers=HEADERS, params=params, timeout=30)
    response.raise_for_status()
    return response.json()


def parse(timestamp):
    return datetime.fromisoformat(timestamp.replace("Z", "+00:00"))


def load_cursor():
    if CURSOR_FILE.exists():
        return json.loads(CURSOR_FILE.read_text())
    return {"created_at": None, "processed_ids": []}


def collect_new_documents(cursor):
    documents = []
    page = 1
    while True:
        inbox = api(
            "/api/inbox/",
            sort_by="created_at",
            sort_order="desc",
            page=page,
            page_size=100,
        )
        for doc in inbox["items"]:
            if cursor["created_at"] and parse(doc["created_at"]) < parse(cursor["created_at"]):
                return documents
            if doc["id"] not in cursor["processed_ids"]:
                documents.append(doc)
        if not inbox["has_next_page"]:
            return documents
        page += 1


def process_document(doc):
    ubl = api(f"/api/documents/{doc['id']}/ubl")
    download = requests.get(ubl["signed_url"], timeout=60)
    download.raise_for_status()
    Path(ubl["file_name"]).write_bytes(download.content)
    print(f"Processed {doc['id']} ({doc['document_type']} {doc.get('invoice_id')})")


cursor = load_cursor()

# Oldest first, so that the cursor only moves forward.
for doc in reversed(collect_new_documents(cursor)):
    process_document(doc)
    if cursor["created_at"] == doc["created_at"]:
        cursor["processed_ids"].append(doc["id"])
    else:
        cursor["processed_ids"] = [doc["id"]]
    cursor["created_at"] = doc["created_at"]
    CURSOR_FILE.write_text(json.dumps(cursor))

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.

curl -X GET "https://api.e-invoice.be/api/documents/doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY"

const documentId = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d";

const response = await fetch(`https://api.e-invoice.be/api/documents/${documentId}`, {
  headers: { Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}` },
});

if (!response.ok) {
  throw new Error(`Get document failed: ${response.status}`);
}

const doc = await response.json();
console.log(doc.document_type, doc.vendor_name, doc.invoice_total);

import os

import requests

document_id = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"

response = requests.get(
    f"https://api.e-invoice.be/api/documents/{document_id}",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()

doc = response.json()
print(doc["document_type"], doc.get("vendor_name"), doc.get("invoice_total"))

<?php
$documentId = 'doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d';

$ch = curl_init("https://api.e-invoice.be/api/documents/{$documentId}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('E_INVOICE_API_KEY')],
]);

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

if ($status !== 200) {
    throw new RuntimeException("Get document failed: {$status}");
}

$doc = json_decode($body, true);
echo $doc['document_type'] . ' ' . $doc['vendor_name'] . PHP_EOL;

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

var documentId = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d";

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.GetAsync($"/api/documents/{documentId}");
response.EnsureSuccessStatusCode();

using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
Console.WriteLine(doc.RootElement.GetProperty("document_type").GetString());

{
  "id": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "created_at": "2026-10-01T09:15:42.118Z",
  "document_type": "INVOICE",
  "state": "RECEIVED",
  "direction": "INBOUND",
  "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",
  "subtotal": "1000.00",
  "total_tax": "210.00",
  "invoice_total": "1210.00",
  "amount_due": "1210.00",
  "items": [
    {
      "description": "Professional services",
      "quantity": "10",
      "unit": "C62",
      "unit_price": "100.00",
      "amount": "1000.00",
      "tax_rate": "21.00",
      "tax": "210.00"
    }
  ],
  "tax_details": [
    {
      "rate": "21.00",
      "amount": "210.00"
    }
  ],
  "payment_details": [
    {
      "iban": "BE68539007547034",
      "payment_reference": "INV-2026-001"
    }
  ],
  "attachments": [
    {
      "id": "doc-att-7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d",
      "file_name": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.pdf",
      "file_type": "application/pdf",
      "file_size": 48213
    }
  ]
}

The response does not contain fields that have no value. Read optional fields defensively. These fields are the most important for a received document:

Field	Value for a received document
`direction`	`INBOUND`
`state`	`RECEIVED`
`document_type`	`INVOICE`, `CREDIT_NOTE`, `SELFBILLING_INVOICE` or `SELFBILLING_CREDIT_NOTE`
`vendor_name`, `vendor_tax_id`, `vendor_company_id`, `vendor_email`, `vendor_address`	The supplier that issued the document
`customer_name`, `customer_tax_id`, `customer_company_id`	The buyer on the document
`invoice_id`, `invoice_date`, `due_date`	The number and the dates that the issuer gave to the document
`subtotal`, `total_tax`, `invoice_total`, `amount_due`	The totals of the document, as strings
`payment_details`	The bank account and the payment reference for the payment
`attachments`	The ID, name, type and size of each attachment. This list has no download URL; see Download the attachments and the PDF
`created_at`	The time at which e-invoice.be created the document record. Use this field for your cursor

A received self-billing document has the type 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.

# 1. Get the signed URL
curl -X GET "https://api.e-invoice.be/api/documents/doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d/ubl" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY"

# 2. Download the file from the signed_url of the response
curl -o invoice.xml "SIGNED_URL"

import { writeFile } from "node:fs/promises";

const documentId = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d";

const response = await fetch(`https://api.e-invoice.be/api/documents/${documentId}/ubl`, {
  headers: { Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}` },
});

if (!response.ok) {
  throw new Error(`Get UBL failed: ${response.status}`);
}

const ubl = await response.json();

const download = await fetch(ubl.signed_url);
if (!download.ok) {
  throw new Error(`UBL download failed: ${download.status}`);
}

await writeFile(ubl.file_name, Buffer.from(await download.arrayBuffer()));

import os
from pathlib import Path

import requests

document_id = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"

response = requests.get(
    f"https://api.e-invoice.be/api/documents/{document_id}/ubl",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
ubl = response.json()

download = requests.get(ubl["signed_url"], timeout=60)
download.raise_for_status()
Path(ubl["file_name"]).write_bytes(download.content)

<?php
$documentId = 'doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d';

$ch = curl_init("https://api.e-invoice.be/api/documents/{$documentId}/ubl");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('E_INVOICE_API_KEY')],
]);

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

if ($status !== 200) {
    throw new RuntimeException("Get UBL failed: {$status}");
}

$ubl = json_decode($body, true);

$download = curl_init($ubl['signed_url']);
curl_setopt_array($download, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => true,
]);
$xml = curl_exec($download);
curl_close($download);

file_put_contents($ubl['file_name'], $xml);

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

var documentId = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d";

using var client = new HttpClient();
using var request = new HttpRequestMessage(
    HttpMethod.Get, $"https://api.e-invoice.be/api/documents/{documentId}/ubl");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("E_INVOICE_API_KEY"));

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();

using var ubl = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var signedUrl = ubl.RootElement.GetProperty("signed_url").GetString();
var fileName = ubl.RootElement.GetProperty("file_name").GetString();

// The signed URL needs no Authorization header.
var xml = await client.GetByteArrayAsync(signedUrl);
await File.WriteAllBytesAsync(fileName!, xml);

{
  "id": "ubl-4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a",
  "file_name": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.xml",
  "file_size": 12840,
  "signed_url": "https://storage.example.com/ubl/doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.xml?X-Amz-Expires=3600&X-Amz-Signature=...",
  "sender_peppol_scheme": "0208",
  "sender_peppol_id": "1018265814",
  "receiver_peppol_scheme": "0208",
  "receiver_peppol_id": "0848934496",
  "validated_at": "2026-10-01T09:15:42.118Z"
}

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.

Do not store signed_url. It stops working after 1 hour. Store the document_id, and request a new URL each time that you need the file. The URL contains its own signature, thus do not add your API key to the download request.

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.

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.

curl -X GET "https://api.e-invoice.be/api/documents/doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d/attachments" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY"

import { writeFile } from "node:fs/promises";

const documentId = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d";

const response = await fetch(
  `https://api.e-invoice.be/api/documents/${documentId}/attachments`,
  { headers: { Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}` } }
);

// 404 means that the document has no attachments.
const attachments = response.status === 404 ? [] : await response.json();

for (const attachment of attachments) {
  const download = await fetch(attachment.file_url);
  if (!download.ok) {
    throw new Error(`Attachment download failed: ${download.status}`);
  }
  await writeFile(attachment.file_name, Buffer.from(await download.arrayBuffer()));
}

import os
from pathlib import Path

import requests

document_id = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"

response = requests.get(
    f"https://api.e-invoice.be/api/documents/{document_id}/attachments",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"},
    timeout=30,
)

# 404 means that the document has no attachments.
if response.status_code == 404:
    attachments = []
else:
    response.raise_for_status()
    attachments = response.json()

for attachment in attachments:
    download = requests.get(attachment["file_url"], timeout=60)
    download.raise_for_status()
    Path(attachment["file_name"]).write_bytes(download.content)

<?php
$documentId = 'doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d';

$ch = curl_init("https://api.e-invoice.be/api/documents/{$documentId}/attachments");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('E_INVOICE_API_KEY')],
]);

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

// 404 means that the document has no attachments.
$attachments = $status === 404 ? [] : json_decode($body, true);

foreach ($attachments as $attachment) {
    $download = curl_init($attachment['file_url']);
    curl_setopt_array($download, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => true,
    ]);
    file_put_contents($attachment['file_name'], curl_exec($download));
    curl_close($download);
}

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

var documentId = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d";

using var client = new HttpClient();
using var request = new HttpRequestMessage(
    HttpMethod.Get, $"https://api.e-invoice.be/api/documents/{documentId}/attachments");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("E_INVOICE_API_KEY"));

var response = await client.SendAsync(request);

// 404 means that the document has no attachments.
if (response.StatusCode != HttpStatusCode.NotFound)
{
    response.EnsureSuccessStatusCode();
    using var attachments = JsonDocument.Parse(await response.Content.ReadAsStringAsync());

    foreach (var attachment in attachments.RootElement.EnumerateArray())
    {
        var fileUrl = attachment.GetProperty("file_url").GetString();
        var fileName = attachment.GetProperty("file_name").GetString();
        await File.WriteAllBytesAsync(fileName!, await client.GetByteArrayAsync(fileUrl));
    }
}

[
  {
    "id": "doc-att-7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d",
    "file_name": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.pdf",
    "file_type": "application/pdf",
    "file_size": 48213,
    "file_url": "https://storage.example.com/attachments/doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.pdf?X-Amz-Expires=3600&X-Amz-Signature=..."
  },
  {
    "id": "doc-att-0f1e2d3c4b5a69788796a5b4c3d2e1f0",
    "file_name": "timesheet-october.xlsx",
    "file_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "file_size": 20417,
    "file_url": "https://storage.example.com/attachments/timesheet-october.xlsx?X-Amz-Expires=3600&X-Amz-Signature=..."
  }
]

This endpoint returns 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.

curl -X GET "https://api.e-invoice.be/api/documents/doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d/attachments/doc-att-7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY"

const documentId = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d";
const attachmentId = "doc-att-7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d";

const response = await fetch(
  `https://api.e-invoice.be/api/documents/${documentId}/attachments/${attachmentId}`,
  { headers: { Authorization: `Bearer ${process.env.E_INVOICE_API_KEY}` } },
);

if (!response.ok) {
  throw new Error(`Get attachment failed: ${response.status}`);
}

const attachment = await response.json();
console.log(attachment.file_url);

import os

import requests

document_id = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d"
attachment_id = "doc-att-7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d"

response = requests.get(
    f"https://api.e-invoice.be/api/documents/{document_id}/attachments/{attachment_id}",
    headers={"Authorization": f"Bearer {os.environ['E_INVOICE_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
attachment = response.json()
print(attachment["file_url"])

<?php
$documentId = 'doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d';
$attachmentId = 'doc-att-7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d';

$ch = curl_init("https://api.e-invoice.be/api/documents/{$documentId}/attachments/{$attachmentId}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('E_INVOICE_API_KEY')],
]);

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

if ($status !== 200) {
    throw new RuntimeException("Get attachment failed: {$status}");
}

$attachment = json_decode($body, true);
echo $attachment['file_url'], PHP_EOL;

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

var documentId = "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d";
var attachmentId = "doc-att-7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d";

using var client = new HttpClient();
using var request = new HttpRequestMessage(
    HttpMethod.Get,
    $"https://api.e-invoice.be/api/documents/{documentId}/attachments/{attachmentId}");
request.Headers.Authorization = new AuthenticationHeaderValue(
    "Bearer", Environment.GetEnvironmentVariable("E_INVOICE_API_KEY"));

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();

using var attachment = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
Console.WriteLine(attachment.RootElement.GetProperty("file_url").GetString());

{
  "id": "doc-att-7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d",
  "file_name": "doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.pdf",
  "file_type": "application/pdf",
  "file_size": 48213,
  "file_url": "https://storage.example.com/attachments/doc-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.pdf?X-Amz-Expires=3600&X-Amz-Signature=..."
}

If the attachment does not exist, the endpoint returns 404 Not Found with "detail": "Document attachment not found". See also Download one attachment.

file_url is valid for 1 hour. Do not store it and do not show it to your users as a permanent link. Store the document_id and the attachment id, and request a new URL when you need the file.

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. 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.

Parameter	Type	Default	Description
`page`	integer	`1`	The page number. The minimum is 1.
`page_size`	integer	`20`	The number of documents on each page. The minimum is 1 and the maximum is 100.
`type`	string	All types	One document type: `INVOICE`, `CREDIT_NOTE`, `DEBIT_NOTE`, `SELFBILLING_INVOICE` or `SELFBILLING_CREDIT_NOTE`.
`sender`	string	No filter	A text in `vendor_name`, `vendor_email`, `vendor_tax_id` or `vendor_company_id`.
`date_from`	date-time	No filter	The first issue date.
`date_to`	date-time	No filter	The last issue date.
`search`	string	No filter	A text in the invoice number, the vendor name, the customer name or the note.
`sort_by`	string	`created_at`	The sort field: `created_at`, `invoice_date`, `due_date`, `invoice_total`, `customer_name`, `vendor_name` or `invoice_id`.
`sort_order`	string	`desc`	The sort direction: `asc` or `desc`.

See List, filter and manage documents for the full description of each parameter. These rules are important for received documents:

date_from and date_to filter on the issue date of the invoice (invoice_date), not on the time of receipt.
sender finds a text in vendor_name, vendor_email, vendor_tax_id or vendor_company_id.
Received documents do not get the type DEBIT_NOTE, thus type=DEBIT_NOTE returns an empty list.

Example: all credit notes from E-INVOICE BV with an issue date in October 2026, the oldest first.

cURL

curl -G "https://api.e-invoice.be/api/inbox/" \
     -H "Authorization: Bearer $E_INVOICE_API_KEY" \
     --data-urlencode "type=CREDIT_NOTE" \
     --data-urlencode "sender=BE1018265814" \
     --data-urlencode "date_from=2026-10-01T00:00:00" \
     --data-urlencode "date_to=2026-10-31T00:00:00" \
     --data-urlencode "sort_by=invoice_date" \
     --data-urlencode "sort_order=asc"

The response has the same paginated shape as the response in Polling.

Shortcut endpoints

Two endpoints return one document type only. They accept page, 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.

Endpoint	Returns
`GET /api/inbox/invoices`	Received documents of the type `INVOICE`
`GET /api/inbox/credit-notes`	Received documents of the type `CREDIT_NOTE`

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

In app.e-invoice.be, select your sandbox company and open Inbox.

Simulate an inbound document

Click Simulate inbound. Select the built-in sample invoice, or upload your own UBL XML file.

Run your integration

The document is in the 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.

A document that you send to your own company does not come into the inbox. In a sandbox company, a send goes to the contact email address of the company and not to Peppol, thus the document gets the SENT state and stays in the outbox. POST /api/documents/ ignores a direction value of INBOUND and always makes an outbound draft. Simulate inbound is the only method to fill the inbox of a sandbox company.

Testing received documents gives the full description. Resellers can do the same step through the Admin API: see Simulate an inbound document.

Frequently asked questions

Can I mark a document as read or processed?

No. The API has no such endpoint and no such field. Keep the processing status in your own system, with the document id as the key. See Prevent double processing.

Must I poll if I use webhooks?

It is not mandatory, but it is good practice. A poll at a long interval (for example one time each hour) finds the documents for which your endpoint missed the webhook. Because you record the processed document IDs, the poll does not process a document twice.

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?

For a production company: make sure that the company is registered as a receiver on Peppol with Look up Peppol participants. For a sandbox company: the inbox stays empty until you use Simulate inbound.

Which document types can I receive?

A received document gets one of four types: 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.

Next Steps

Webhooks

Get an event for each received document and verify its signature.

List, filter and manage documents

Use the filters, the sort options and the pagination of the inbox.

Test mode and sandbox companies

Use a sandbox company and Simulate inbound to test your integration.

Document lifecycle and delivery tracking

Read the timeline of a received document.

Getting started

Send documents

Receive and manage

Other input formats

Integrate

SDKs and tools

Resellers

Reference

Overview

Prerequisites

How a document arrives

Find new documents

Webhook (recommended)

Polling

Prevent double processing

Get the document

Download the original UBL

Download the attachments and the PDF

List the attachments

Get one attachment

Filter the inbox

Shortcut endpoints

Test with a sandbox company

Frequently asked questions

Next Steps

Webhooks

List, filter and manage documents

Test mode and sandbox companies

Document lifecycle and delivery tracking

​Overview

​Prerequisites

​How a document arrives

​Find new documents

​Webhook (recommended)

​Polling

​Prevent double processing

​Get the document

​Download the original UBL

​Download the attachments and the PDF

​List the attachments

​Get one attachment

​Filter the inbox

​Shortcut endpoints

​Test with a sandbox company

​Frequently asked questions

​Next Steps

Webhooks

List, filter and manage documents

Test mode and sandbox companies

Document lifecycle and delivery tracking

Overview

Prerequisites

How a document arrives

Find new documents

Webhook (recommended)

Polling

Prevent double processing

Get the document

Download the original UBL

Download the attachments and the PDF

List the attachments

Get one attachment

Filter the inbox

Shortcut endpoints

Test with a sandbox company

Frequently asked questions

Next Steps