Authentication
Type
APIKEY — API KEY
Location
query / param:
apikeyFallback via query/body param "apikey"
GET https://api.peppox.com//sendsms/?apikey=YOUR_API_KEY
Invoice Management
/invoice/add
• Methods:
POST
Add a sales invoice header
Creates a new invoice header in DRAFT status. The endpoint records all supplier and customer information, issue dates, payment terms, and delivery details. Supplier data are automatically loaded from your API key registration (customer_api).
POST
/invoice/add
• Rate: 60 req/min
• Auth required
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
apikey |
string | Yes | Your Peppox API key (from your registered supplier account). | ||
network |
string | No | Optional network identifier (Peppol by default). | ||
inv_id |
string | No | Optional internal invoice number. | ||
issue_date |
string | Yes | Invoice issue date (YYYY-MM-DD). | ||
due_date |
string | No | Invoice due date (YYYY-MM-DD). | ||
invoice_type_code |
string | No | 380 | Peppol invoice type code (e.g. 380 = Invoice, 381 = CreditNote). | |
currency |
string | No | EUR | ISO currency code. | |
accounting_cost |
string | No | Internal accounting code reference. | ||
buyer_reference |
string | No | Buyer reference / PO number. | ||
payment.means_code |
string | No | 1 | Means of payment (Peppol code list). | |
payment.payment_id |
string | No | Payment identifier / reference. | ||
payment.iban |
string | No | Payee IBAN. | ||
payment.account_name |
string | No | Payee account holder name. | ||
payment.bic |
string | No | Payee BIC/SWIFT code. | ||
payment.terms_note |
string | No | Payment terms note. | ||
delivery.date |
string | No | Delivery date. | ||
delivery.location_scheme |
string | No | 0088 | Delivery location scheme identifier. | |
delivery.location_id |
string | No | Delivery location ID. | ||
delivery.street |
string | No | Delivery address street. | ||
delivery.city |
string | No | Delivery address city. | ||
delivery.postal |
string | No | Delivery address postal code. | ||
delivery.country |
string | No | Delivery address country code. | ||
delivery.party_name |
string | No | Delivery party name. | ||
customer.endpoint_scheme |
string | No | 0208 | Customer Peppol scheme ID. | |
customer.endpoint_id |
string | No | Customer Peppol Participant ID. | ||
customer.name |
string | No | Customer name. | ||
customer.street |
string | No | Customer street. | ||
customer.city |
string | No | Customer city. | ||
customer.postal |
string | No | Customer postal code. | ||
customer.country |
string | No | Customer country code. | ||
customer.vat_id |
string | No | Customer VAT number. | ||
customer.company_id_scheme |
string | No | 0208 | Customer company ID scheme. | |
customer.company_id |
string | No | Customer company ID (national number). | ||
customer.phone |
string | No | Customer contact phone. | ||
customer.email |
string | No | Customer contact email. |
Request examples
CURL
PYTHON
curl -X POST "https://api.peppox.com/invoice/add/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "{
"issue_date": "2025-10-17",
"due_date": "2025-11-17",
"customer": {
"endpoint_id": "9915:BE0123456789",
"name": "ACME SPRL",
"country": "BE"
},
"payment": {
"iban": "BE12345678901234",
"bic": "GEBABEBB",
"account_name": "Peppox Supplier"
}
}"
Responses
Status: 200 — Invoice successfully created (draft).
JSON
{
"ok": true,
"invoice_guid": "inv-8c3b4a99-2025-10-17",
"status": "DRAFT"
}
Status: 400 — Invalid or missing fields.
Status: 401 — Invalid or expired API key.
Status: 500 — Internal server or database error.
/invoice_line/add
• Methods:
POST
Add an invoice line to an existing invoice
Adds a new line to an existing invoice (identified by invoice_guid). Supports unit, quantity, price, VAT category, and product identification codes.
POST
/invoice_line/add
• Rate: 60 req/min
• Auth required
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
apikey |
string | Yes | Your Peppox API key (required for authentication). | ||
invoice_guid |
string | Yes | The unique invoice GUID returned from /invoice/add. | ||
line_id |
string | No | Optional internal line identifier (defaults to generated GUID). | ||
quantity |
number | Yes | Quantity of the item or service. | ||
unit_code |
string | No | Unit code according to UNECE Rec 20 (e.g. H87 for “piece”). | ||
price_amount |
number | Yes | Unit price (excluding tax). | ||
item_description |
string | No | Description of the item or service. | ||
item_name |
string | No | Item name or title. | ||
seller_item_id |
string | No | Seller internal item ID or SKU. | ||
std_item_id_scheme |
string | No | 0088 | Standard scheme ID for item identification (e.g. GTIN). | |
std_item_id |
string | No | Standardized item ID (GTIN, EAN, etc.). | ||
origin_country |
string | No | Country of origin (ISO 3166-1 alpha-2). | ||
tax_category |
string | No | VAT category code (e.g. S, Z, AE). | ||
tax_percent |
number | No | VAT rate percentage (e.g. 21.00). |
Request examples
CURL
PYTHON
curl -X POST "https://api.peppox.com/invoice_line/add/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "{
"invoice_guid": "inv-8c3b4a99-2025-10-17",
"quantity": 2,
"unit_code": "H87",
"price_amount": 49.99,
"item_name": "Consulting service",
"tax_percent": 21
}"
Responses
Status: 200 — Invoice line successfully added.
JSON
{
"ok": true,
"line_guid": "line-2b4fa3c1-2025-10-17"
}
Status: 400 — Invalid parameters (missing invoice_guid or invalid numeric fields).
Status: 401 — Invalid or expired API key.
Status: 500 — Internal database or server error.
/invoice_attach_pdf/add
• Methods:
POST
Attach a PDF to an existing invoice
Attaches a PDF document (via upload, Base64, or remote URL) to an existing invoice identified by invoice_guid. Only one attachment per invoice is stored; any previous file is replaced.
POST
/invoice_attach_pdf/add
• Rate: 30 req/min
• Auth required
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
apikey |
string | Yes | Your Peppox API key (authentication). | ||
invoice_guid |
string | Yes | The GUID of the invoice to attach the PDF to. | ||
doc_id |
string | No | Optional document identifier (defaults to invoice ID or a generated UUID). | ||
filename |
string | No | attachment.pdf | Attachment file name (e.g. invoice.pdf). | |
mime |
string | No | application/pdf | MIME type of the file. | |
content_base64 |
string | No | PDF content as Base64 string. Accepts data URI format. | ||
file_url |
string | No | Remote HTTPS URL of a PDF to download and attach. | ||
file |
file | No | File upload field (multipart/form-data). |
Request examples
CURL
CURL
CURL
curl -X POST "https://api.peppox.com/invoice_attach_pdf/add/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "invoice_guid=inv-8c3b4a99-2025-10-17" \
-F "file=@invoice.pdf"
Responses
Status: 200 — PDF successfully attached to the invoice.
JSON
{
"ok": true,
"invoice_guid": "inv-8c3b4a99-2025-10-17",
"doc_id": "DOC-1452",
"filename": "invoice-2025-10.pdf",
"mime": "application/pdf",
"size_bytes": 184527
}
Status: 400 — Invalid parameters or missing content (no Base64, file, or URL).
Status: 401 — Invalid or expired API key.
Status: 404 — Invoice not found.
Status: 500 — Internal server or database error.
XML Generation
/xml/generate
• Methods:
POST
Generate a UBL XML file for an invoice or Credit Note
Combines invoice/credit note header, lines, and attached PDF (if any) into a Peppol-compliant UBL 3.0 XML document. Returns the local path to the generated file and updates the invoice/credit note status to XML_BUILT.
POST
/xml/generate
• Rate: 30 req/min
• Auth required
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
apikey |
string | Yes | Your Peppox API key for authentication. | ||
invoice_guid |
string | Yes | The unique identifier of the invoice to convert to XML. | ||
guid |
string | No | Alternative key for invoice_guid. |
Request examples
CURL
PYTHON
curl -X POST "https://api.peppox.com/xml/generate/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d "{
"invoice_guid": "inv-8c3b4a99-2025-10-17"
}"
Responses
Status: 200 — XML successfully generated and stored on server.
JSON
{
"ok": true,
"status": "XML_BUILT",
"xml_path": "/var/www/vhosts/peppox.com/httpdocs/invoices_xml/inv-8c3b4a99-2025-10-17.xml"
}
Status: 400 — Missing invoice_guid or invoice lines.
Status: 401 — Invalid or expired API key.
Status: 404 — Invoice not found.
Status: 500 — Internal XML generation or write error.
Credit Notes
/creditnote/add
• Methods:
POST
Add a credit note header
Creates a new credit note header in DRAFT status. Supplier data are automatically loaded from the API key account, while customer, payment, and delivery fields are accepted from the request.
POST
/creditnote/add
• Rate: 60 req/min
• Auth required
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
apikey |
string | Yes | Your Peppox API key. | ||
network |
string | No | Optional network identifier. | ||
creditnote_id |
string | No | Preferred credit note number/identifier. | ||
cn_id |
string | No | Alternative alias for credit note ID. | ||
credit_note_id |
string | No | Alternative alias for credit note ID. | ||
inv_id |
string | No | Alternative legacy identifier. | ||
issue_date |
string | Yes | Credit note issue date (YYYY-MM-DD). | ||
due_date |
string | No | Due date (YYYY-MM-DD). | ||
invoice_type_code |
string | No | 381 | Document type code. Default 381 = Credit Note. | |
currency |
string | No | EUR | ISO currency code. | |
accounting_cost |
string | No | Internal accounting reference. | ||
buyer_reference |
string | No | Buyer reference / customer PO reference. | ||
payment.means_code |
string | No | 1 | Payment means code. | |
payment.payment_id |
string | No | Payment reference. | ||
payment.iban |
string | No | Payee IBAN. | ||
payment.account_name |
string | No | Payee account name. | ||
payment.bic |
string | No | Payee BIC / SWIFT. | ||
payment.terms_note |
string | No | Payment terms note. | ||
delivery.date |
string | No | Delivery date. | ||
delivery.location_scheme |
string | No | 0088 | Delivery location scheme. | |
delivery.location_id |
string | No | Delivery location identifier. | ||
delivery.street |
string | No | Delivery street. | ||
delivery.city |
string | No | Delivery city. | ||
delivery.postal |
string | No | Delivery postal code. | ||
delivery.country |
string | No | Delivery country code. | ||
delivery.party_name |
string | No | Delivery party name. | ||
supplier.endpoint_scheme |
string | No | 0208 | Supplier endpoint scheme. Supplier values are otherwise loaded from the API account. | |
customer.endpoint_scheme |
string | No | 0208 | Customer endpoint scheme. | |
customer.endpoint_id |
string | No | Customer endpoint ID. | ||
customer.name |
string | No | Customer legal name. | ||
customer.street |
string | No | Customer street. | ||
customer.city |
string | No | Customer city. | ||
customer.postal |
string | No | Customer postal code. | ||
customer.country |
string | No | Customer country code. | ||
customer.vat_id |
string | No | Customer VAT number. | ||
customer.company_id_scheme |
string | No | 0208 | Customer company ID scheme. | |
customer.company_id |
string | No | Customer company ID. | ||
customer.phone |
string | No | Customer phone. | ||
customer.email |
string | No | Customer email. |
Request examples
CURL
PYTHON
curl -X POST "https://api.peppox.com/creditnote/add/"
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d "{
"creditnote_id": "CN-2025-001",
"issue_date": "2025-10-17",
"currency": "EUR",
"customer": {
"endpoint_id": "9915:BE0123456789",
"name": "ACME SPRL",
"country": "BE"
}
}"
Responses
Status: 200 — Credit note successfully created.
JSON
{
"ok": true,
"invoice_guid": "cn-8c3b4a99-2025-10-17",
"document_type": "CREDIT_NOTE",
"status": "DRAFT"
}
Status: 400 — Invalid or missing fields.
Status: 401 — Invalid or expired API key.
Status: 500 — Internal server or database error.
/creditnote_line/add
• Methods:
POST
Add a credit note line
Adds a line to an existing credit note. Automatically accepts aliases for creditnote_guid and computes tax_category from tax_percent when possible.
POST
/creditnote_line/add
• Rate: 60 req/min
• Auth required
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
apikey |
string | Yes | Your Peppox API key. | ||
creditnote_guid |
string | Yes | The target credit note GUID. | ||
invoice_guid |
string | No | Alias for creditnote_guid. | ||
guid |
string | No | Alias for creditnote_guid. | ||
line_id |
string | No | Optional internal line identifier. | ||
order_line_id |
string | No | Alias for line_id. | ||
quantity |
number | Yes | Line quantity. | ||
qty |
number | No | Alias for quantity. | ||
q |
number | No | Alias for quantity. | ||
unit_code |
string | No | Unit code. | ||
unit |
string | No | Alias for unit_code. | ||
u |
string | No | Alias for unit_code. | ||
price_amount |
number | Yes | Unit price amount. | ||
price |
number | No | Alias for price_amount. | ||
unit_price |
number | No | Alias for price_amount. | ||
item_description |
string | No | Line description. | ||
description |
string | No | Alias for item_description. | ||
desc |
string | No | Alias for item_description. | ||
item_name |
string | No | Item name/title. | ||
name |
string | No | Alias for item_name. | ||
title |
string | No | Alias for item_name. | ||
seller_item_id |
string | No | Seller item ID / SKU. | ||
seller_id |
string | No | Alias for seller_item_id. | ||
sku |
string | No | Alias for seller_item_id. | ||
std_item_id_scheme |
string | No | 0088 | Standard item identification scheme. | |
std_scheme |
string | No | Alias for std_item_id_scheme. | ||
scheme |
string | No | Alias for std_item_id_scheme. | ||
std_item_id |
string | No | Standard item ID (EAN, GTIN, etc.). | ||
gtin |
string | No | Alias for std_item_id. | ||
ean |
string | No | Alias for std_item_id. | ||
origin_country |
string | No | Country of origin. | ||
country |
string | No | Alias for origin_country. | ||
tax_category |
string | No | VAT category code. Automatically forced to S or Z depending on tax_percent. | ||
tax_cat |
string | No | Alias for tax_category. | ||
vat_category |
string | No | Alias for tax_category. | ||
tax_percent |
number | No | VAT percentage. | ||
vat_rate |
number | No | Alias for tax_percent. | ||
tax |
number | No | Alias for tax_percent. | ||
vat |
number | No | Alias for tax_percent. |
Request examples
CURL
PYTHON
curl -X POST "https://api.peppox.com/creditnote_line/add/"
-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"
-d "{
"creditnote_guid": "cn-8c3b4a99-2025-10-17",
"quantity": 2,
"unit_code": "H87",
"price_amount": 49.99,
"item_name": "Returned consulting service",
"tax_percent": 21
}"
Responses
Status: 200 — Credit note line successfully added.
JSON
{
"ok": true,
"line_guid": "line-2b4fa3c1-2025-10-17"
}
Status: 400 — Missing required values such as creditnote_guid, quantity, or price_amount.
Status: 401 — Invalid or expired API key.
Status: 500 — Internal database error.
/creditnote_attach_pdf/add
• Methods:
POST
Attach a PDF to a credit note
Attaches a PDF document to an existing credit note using multipart upload, Base64 payload, or remote URL. Previous attachment is replaced.
POST
/creditnote_attach_pdf/add
• Rate: 30 req/min
• Auth required
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
apikey |
string | Yes | Your Peppox API key. | ||
creditnote_guid |
string | Yes | The credit note GUID to attach the PDF to. | ||
invoice_guid |
string | No | Alias for creditnote_guid. | ||
guid |
string | No | Alias for creditnote_guid. | ||
doc_id |
string | No | Optional document identifier. Defaults to inv_id or a generated UUID. | ||
filename |
string | No | attachment.pdf | Attachment filename. | |
mime |
string | No | application/pdf | Attachment MIME type. | |
content_base64 |
string | No | PDF content encoded as Base64. | ||
pdf_base64 |
string | No | Alias for content_base64. | ||
file_url |
string | No | HTTP/HTTPS URL of the PDF to download and attach. | ||
pdf_url |
string | No | Alias for file_url. | ||
file |
file | No | Multipart uploaded file. |
Request examples
CURL
CURL
CURL
curl -X POST "https://api.peppox.com/creditnote_attach_pdf/add/"
-H "Authorization: Bearer YOUR_API_KEY"
-F "creditnote_guid=cn-8c3b4a99-2025-10-17"
-F "file=@creditnote.pdf"
Responses
Status: 200 — PDF successfully attached to the credit note.
JSON
{
"ok": true,
"creditnote_guid": "cn-8c3b4a99-2025-10-17",
"doc_id": "CN-2025-001",
"filename": "creditnote.pdf",
"mime": "application/pdf",
"size_bytes": 184527
}
Status: 400 — Invalid request: missing creditnote_guid, invalid Base64, invalid URL, or no content provided.
Status: 401 — Invalid or expired API key.
Status: 404 — Credit note not found.
Status: 500 — Internal database or file handling error.
Sent Documents
/doc-sent/header/list
• Methods:
GET
List sent invoice headers
Lists sent sales invoice headers for a supplier. Supports keyword search, date filters, Peppol status filters, local status filters, raw response inclusion, sorting, and pagination.
GET
/doc-sent/header/list
• Rate: 300 req/min
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
supplier_id |
string | Yes | Required supplier identifier. This value maps to invoices.apikey. | ||
q |
string | No | Keyword search across invoice header fields. | ||
page |
integer | No | 1 | Page number. | |
per_page |
integer | No | 300 | Rows per page. Maximum: 300. | |
date |
string | No | Exact date filter in YYYY-MM-DD format. | ||
date_from |
string | No | Start date for period filter in YYYY-MM-DD format. | ||
date_to |
string | No | End date for period filter in YYYY-MM-DD format. | ||
date_field |
string | No | sent_at | Date field used for date/date_from/date_to. Allowed: issue_date, due_date, delivery_date, xml_built_at, sent_at, created_at, updated_at, status_from_peppol_date. | |
status_from_peppol |
string | No | Filter by Peppol status. Supports CSV values. | ||
peppol_status |
string | No | Alias for status_from_peppol. | ||
status |
string | No | Alias for status_from_peppol. | ||
local_status |
string | No | Filter by local invoice status from invoices.status. Supports CSV values. | ||
include_raw |
boolean | No | 0 | Set to 1 to include sent_reply_api and all_response_api in the response. | |
search_raw |
boolean | No | 0 | Set to 1 to include sent_reply_api and all_response_api in keyword search. | |
sort_by |
string | No | sent_at | Sort column. Allowed: id, invoice_guid, inv_id, issue_date, due_date, xml_built_at, sent_at, status, created_at, updated_at, status_from_peppol, status_from_peppol_date, c_name, s_name, currency, network. | |
sort_dir |
string | No | DESC | Sort direction: ASC or DESC. |
Request examples
CURL
CURL
CURL
PYTHON
curl "https://api.peppox.com/doc-sent/header/list/?supplier_id=YOUR_SUPPLIER_ID"
Responses
Status: 200 — Success — returns invoice headers with filters, sort information, pagination and data rows.
JSON
{
"ok": true,
"endpoint": "doc-sent/header/list",
"method": "GET",
"filters": {
"supplier_id": "YOUR_SUPPLIER_ID",
"q": "",
"date": "",
"date_from": "2025-10-01",
"date_to": "2025-10-31",
"date_field": "sent_at",
"status_from_peppol": "sent",
"local_status": "",
"include_raw": "0",
"search_raw": "0"
},
"sort": {
"sort_by": "sent_at",
"sort_dir": "DESC"
},
"pagination": {
"page": 1,
"per_page": 300,
"total": 1,
"total_pages": 1,
"has_prev": false,
"has_next": false
},
"count": 1,
"data": [
{
"id": 125,
"invoice_guid": "inv-8c3b4a99-2025-10-17",
"inv_id": "INV-2025-001",
"issue_date": "2025-10-17",
"due_date": "2025-11-17",
"invoice_type_code": "380",
"currency": "EUR",
"buyer_reference": "PO-12345",
"s_name": "Supplier Company",
"s_endpoint_id": "0208:0123456789",
"c_name": "Customer Company",
"c_endpoint_id": "0208:0987654321",
"status": "SENT",
"sent_at": "2025-10-17 14:30:00",
"sent_http_code": 200,
"network": "peppol",
"status_from_peppol": "sent",
"status_from_peppol_date": "2025-10-17 14:31:00",
"status_from_peppol_error": null,
"flowin_invoice_id_from_sent_reply_api": "flowin-doc-id-123",
"flowin_document_endpoint_used": "/peppol/suppliers/.../invoices"
}
]
}
Status: 400 — Missing required supplier_id.
Status: 500 — Server error.
/doc-sent/lines/list
• Methods:
GET
List sent invoice lines
Lists the lines of a sent invoice using supplier_id and invoice_guid. The supplier_id must match invoices.apikey for security.
GET
/doc-sent/lines/list
• Rate: 300 req/min
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
supplier_id |
query | string | Yes | Required supplier identifier. This value must match invoices.apikey. | |
invoice_guid |
query | string | Yes | Invoice GUID used to list invoice lines. | |
q |
query | string | No | Optional keyword search across invoice line fields. | |
page |
query | integer | No | 1 | Page number. |
per_page |
query | integer | No | 300 | Rows per page. Maximum: 300. |
Request examples
CURL
CURL
PYTHON
curl "https://api.peppox.com/doc-sent/lines/list/?supplier_id=YOUR_SUPPLIER_ID&invoice_guid=inv-8c3b4a99-2025-10-17"
Responses
Status: 200 — Success — returns invoice metadata, filters, pagination and invoice lines.
JSON
{
"ok": true,
"endpoint": "doc-send/lines/list",
"invoice": {
"invoice_guid": "inv-8c3b4a99-2025-10-17",
"inv_id": "INV-2025-001",
"status": "SENT",
"sent_at": "2025-10-17 14:30:00"
},
"filters": {
"supplier_id": "YOUR_SUPPLIER_ID",
"invoice_guid": "inv-8c3b4a99-2025-10-17",
"q": "consulting"
},
"pagination": {
"page": 1,
"per_page": 300,
"total": 1,
"total_pages": 1,
"has_prev": false,
"has_next": false
},
"count": 1,
"data": [
{
"id": 1,
"invoice_guid": "inv-8c3b4a99-2025-10-17",
"line_guid": "line-001",
"line_id": "1",
"quantity": "2.00",
"unit_code": "H87",
"price_amount": "49.99",
"item_description": "Consulting service",
"item_name": "Consulting",
"seller_item_id": "SKU-001",
"std_item_id_scheme": "0088",
"std_item_id": null,
"origin_country": "BE",
"tax_category": "S",
"tax_percent": "21.00",
"created_at": "2025-10-17 14:00:00",
"updated_at": null
}
]
}
Status: 400 — Missing required supplier_id or invoice_guid.
Status: 404 — Invoice not found or not allowed for this supplier_id.
Status: 500 — Server error.
Received Documents
/doc-received/header/list
• Methods:
GET
List received purchase invoice headers
Lists purchase invoice headers received by a supplier through Peppol. Supports keyword search, date filters, import status, document type code, raw fields, sorting and pagination.
GET
/doc-received/header/list
• Rate: 300 req/min
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
supplier_id |
string | Yes | Required supplier identifier. This value maps to peppox_inbound_purchase_invoices.supplier_id. | ||
q |
string | No | Keyword search across received invoice header fields. | ||
page |
integer | No | 1 | Page number. | |
per_page |
integer | No | 300 | Rows per page. Maximum: 300. | |
date |
string | No | Exact date filter in YYYY-MM-DD format. | ||
date_from |
string | No | Start date for period filter in YYYY-MM-DD format. | ||
date_to |
string | No | End date for period filter in YYYY-MM-DD format. | ||
date_field |
string | No | api_created_at | Date field used for date/date_from/date_to. Allowed: api_created_at, issue_date, due_date, tax_point_date, created_at, updated_at. | |
import_status |
string | No | Filter by import status. Supports CSV values. | ||
status |
string | No | Alias for import_status. | ||
document_type_code |
string | No | Filter by document type code. Supports CSV values. Example: 380 invoice, 381 credit note. | ||
type_code |
string | No | Alias for document_type_code. | ||
include_raw |
boolean | No | 0 | Set to 1 to include customization_id, profile_id, xml_without_pdf, api_attributes_json, parser_json and notification_sent_by_email_response. | |
search_raw |
boolean | No | 0 | Set to 1 to search inside raw/long fields. | |
sort_by |
string | No | api_created_at | Sort column. Allowed: id, customer_id, supplier_id, flowin_document_id, api_created_at, document_type_code, document_number, issue_date, due_date, tax_point_date, currency, supplier_name, customer_name, total_excl_vat, total_vat, total_incl_vat, payable_amount, import_status, created_at, updated_at. | |
sort_dir |
string | No | DESC | Sort direction: ASC or DESC. |
Request examples
CURL
CURL
CURL
PYTHON
curl "https://api.peppox.com/doc-received/header/list/?supplier_id=327c58aa-f3e1-4c56-ae75-327c58916148"
Responses
Status: 200 — Success — returns received purchase invoice headers with filters, sorting, pagination and data rows.
JSON
{
"ok": true,
"endpoint": "doc-received/header/list",
"method": "GET",
"filters": {
"supplier_id": 327c58aa-f3e1-4c56-ae75-327c58916148",
"q": "",
"date": "",
"date_from": "2025-10-01",
"date_to": "2025-10-31",
"date_field": "api_created_at",
"import_status": "imported",
"document_type_code": "380",
"include_raw": "0",
"search_raw": "0"
},
"sort": {
"sort_by": "api_created_at",
"sort_dir": "DESC"
},
"pagination": {
"page": 1,
"per_page": 300,
"total": 1,
"total_pages": 1,
"has_prev": false,
"has_next": false
},
"count": 1,
"data": [
{
"id": 25,
"customer_id": 7,
"supplier_id": 327c58aa-f3e1-4c56-ae75-327c58916148",
"document_id": "flowin-doc-id-123",
"environment": "production",
"api_created_at": "2025-10-17 14:30:00",
"document_type_label": "Invoice",
"document_type_code": "380",
"document_number": "INV-2025-001",
"issue_date": "2025-10-17",
"due_date": "2025-11-17",
"tax_point_date": "2025-10-17",
"currency": "EUR",
"buyer_reference": "PO-12345",
"order_reference": "ORD-987",
"supplier_name": "Supplier Company",
"supplier_company_id": "0123456789",
"supplier_endpoint_id": "0208:0123456789",
"supplier_vat_id": "BE0123456789",
"supplier_street": "Supplier Street 1",
"supplier_city": "Brussels",
"supplier_zip": "1000",
"supplier_country": "BE",
"customer_name": "Customer Company",
"customer_company_id": "0987654321",
"customer_endpoint_id": "0208:0987654321",
"customer_vat_id": "BE0987654321",
"customer_street": "Customer Street 2",
"customer_city": "Namur",
"customer_zip": "5000",
"customer_country": "BE",
"total_excl_vat": "100.00",
"total_vat": "21.00",
"total_incl_vat": "121.00",
"payable_amount": "121.00",
"line_extension_amount": "100.00",
"tax_exclusive_amount": "100.00",
"tax_inclusive_amount": "121.00",
"allowance_total_amount": "0.00",
"charge_total_amount": "0.00",
"prepaid_amount": "0.00",
"payment_means_code": "30",
"payment_id": "INV-2025-001",
"iban": "BE12345678901234",
"bic": "GEBABEBB",
"has_embedded_pdf": 1,
"created_at": "2025-10-17 14:31:00"
}
]
}
Status: 400 — Missing required supplier_id.
Status: 500 — Server error.
/doc-received/lines/list
• Methods:
GET
List received purchase invoice lines
Lists the lines of a received purchase invoice using supplier_id and document_id. The document_id maps to peppox_inbound_purchase_invoices.flowin_document_id.
GET
/doc-received/lines/list
• Rate: 300 req/min
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
supplier_id |
string | Yes | Required supplier identifier. | ||
document_id |
string | Yes | Required received document ID. Maps to flowin_document_id. | ||
q |
string | No | Keyword search across received invoice line fields. | ||
page |
integer | No | 1 | Page number. | |
per_page |
integer | No | 300 | Rows per page. Maximum: 300. | |
include_raw |
boolean | No | 0 | Set to 1 to include raw_line_xml and parser_json. | |
search_raw |
boolean | No | 0 | Set to 1 to search inside raw_line_xml and parser_json. | |
sort_by |
string | No | line_no | Sort column. Allowed: id, invoice_header_id, customer_id, supplier_id, flowin_document_id, line_no, line_id, item_name, quantity, unit_code, unit_price, vat_rate, line_total_excl_vat, line_total_vat, line_total_incl_vat, currency, created_at. | |
sort_dir |
string | No | ASC | Sort direction: ASC or DESC. |
Request examples
CURL
CURL
CURL
PYTHON
curl "https://api.peppox.com/doc-received/lines/list/?supplier_id=327c58aa-f3e1-4c56-ae75-327c58916148&document_id=e1de8615-ce41-425a-ba88-0b834bf3ccf9"
Responses
Status: 200 — Success — returns received invoice metadata, filters, sorting, pagination and line rows.
JSON
{
"ok": true,
"endpoint": "doc-received/lines/list",
"method": "GET",
"invoice": {
"id": 25,
"customer_id": 7,
"supplier_id": 327c58aa-f3e1-4c56-ae75-327c58916148",
"document_id": "e1de8615-ce41-425a-ba88-0b834bf3ccf9",
"document_number": "INV-2025-001",
"document_type_code": "380",
"document_type_label": "Invoice",
"issue_date": "2025-10-17",
"due_date": "2025-11-17",
"currency": "EUR",
"supplier_name": "Supplier Company",
"customer_name": "Customer Company",
"total_excl_vat": "100.00",
"total_vat": "21.00",
"total_incl_vat": "121.00",
"payable_amount": "121.00",
"import_status": "imported",
"api_created_at": "2025-10-17 14:30:00"
},
"filters": {
"supplier_id": 327c58aa-f3e1-4c56-ae75-327c58916148",
"document_id": "e1de8615-ce41-425a-ba88-0b834bf3ccf9",
"q": "",
"include_raw": "0",
"search_raw": "0"
},
"sort": {
"sort_by": "line_no",
"sort_dir": "ASC"
},
"pagination": {
"page": 1,
"per_page": 300,
"total": 1,
"total_pages": 1,
"has_prev": false,
"has_next": false
},
"count": 1,
"data": [
{
"supplier_id": 327c58aa-f3e1-4c56-ae75-327c58916148",
"document_id": "e1de8615-ce41-425a-ba88-0b834bf3ccf9",
"line_id": "1",
"description": "Consulting service",
"item_name": "Consulting",
"item_seller_id": "SKU-001",
"item_buyer_id": null,
"quantity": "2.00",
"unit_code": "H87",
"unit_price": "50.00",
"base_quantity": "1.00",
"vat_category_id": "S",
"vat_rate": "21.00",
"vat_scheme": "VAT",
"line_total_excl_vat": "100.00",
"line_total_vat": "21.00",
"line_total_incl_vat": "121.00",
"currency": "EUR",
"created_at": "2025-10-17 14:31:00"
}
]
}
Status: 400 — Missing required supplier_id or document_id.
Status: 404 — Received invoice not found or not allowed for this supplier_id/document_id.
Status: 500 — Server error.
PDF to Peppol
/pdf2peppol/add
• Methods:
POST
Upload a PDF for Peppol conversion
Receives a PDF document by file upload, base64 or URL. Peppox stores it in the PDF to Peppol queue and starts the conversion process. The document is not sent immediately to Peppol: it must first be processed, checked, confirmed, then sent.
POST
/pdf2peppol/add
• Rate: 50 PDF/month by default
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
supplier_id |
string | Yes | Supplier identifier. Alias accepted: apikey or api_key. | ||
pdf_url |
string | No | Public URL of the PDF to import. Alias: file_url, document_url, url. | ||
pdf_base64 |
body | string | No | PDF content encoded in base64. Alias: content_base64, file_base64, document_base64, base64. | |
pdf |
file | No | PDF file upload. Accepted field names: pdf, file, invoice_pdf, document, pdf_file. | ||
filename |
string | No | document.pdf | Original filename. Used when sending base64 or URL. | |
network |
string | No | production | Peppol network. Allowed: production or integration. Alias: net_work, environment. | |
document_type_code |
string | No | 380 | Document type. 380 = sales invoice, 381 = credit note. Aliases: invoice_type_code, document_type, type. |
Request examples
CURL
CURL
CURL
curl "https://api.peppox.com/pdf2peppol/add/?supplier_id=de5c7119-0f03-4058-9d3b-9f9520c2a46e&pdf_url=https://peppox.com/invoice2.pdf"
Responses
Status: 200 — PDF accepted and added to the conversion queue.
JSON
{
"success": true,
"message": "PDF document received. It is now waiting for processing.",
"queue_guid": "pdf-6e9466501393cfbb32b1ec80498a1dfa",
"status": "pending",
"from_api": 1,
"supplier_id": "de5c569-0f03-4248-9dae-9f9520c2a477e",
"queue_customer_id": 12,
"document_type_code": "380",
"document_type_label": "Sales invoice",
"network": "production",
"pdf_source": "url",
"filename": "invoice2.pdf",
"monthly_limit": {
"limit": 50,
"used": 4,
"remaining_before_upload": 46
}
}
Status: 400 — Invalid request, invalid supplier, invalid PDF, file too large, or monthly limit reached.
/pdf2peppol/check
• Methods:
GET
Check PDF to Peppol conversion
Returns the conversion status, extracted header data, extracted lines, PDF link and Peppol readiness checks for a queued PDF document.
GET
/pdf2peppol/check
• Rate: 300 req/min
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
supplier_id |
string | Yes | Supplier identifier. Alias accepted: apikey or api_key. | ||
queue_guid |
string | Yes | Queue GUID returned by /pdf2peppol/add. Alias: guid. | ||
download_pdf |
query | boolean | No | 0 | If set to 1, returns the original PDF instead of JSON. |
Request examples
CURL
CURL
curl "https://api.peppox.com/pdf2peppol/check/?supplier_id=de5c7119-0f03-4058-9d3b-9f9520c2a46e&queue_guid=pdf-6e9466501393cfbb32b1ec80498a1dfa"
Responses
Status: 200 — Conversion loaded successfully.
JSON
{
"success": true,
"message": "PDF to Peppol conversion loaded successfully.",
"queue": {
"queue_guid": "pdf-6e9466501393cfbb32b1ec80498a1dfa",
"supplier_id": "de5c569-0f03-4248-9dae-9f9520c2a477e",
"document_type_code": "380",
"document_type_label": "Sales invoice",
"network": "production",
"filename": "invoice.pdf",
"pdf_url": "https://api.peppox.com/pdf2peppol/check/?download_pdf=1&supplier_id=de5c569-0f03-4248-9dae-9f9520c2a477e&queue_guid=pdf-6e9466501393cfbb32b1ec80498a1dfa",
"processing": {
"status": "parsed",
"is_waiting": false,
"is_finished": true,
"has_error": false
},
"verification": {
"confirmed": false,
"confirmed_at": ""
},
"peppol_send": {
"status": "blocked",
"requested_at": "",
"completed_at": "",
"peppox_invoice_guid": "",
"error": ""
}
},
"peppol_readiness": {
"ready_for_peppol": true,
"can_be_verified": true,
"verification_confirmed": false,
"can_be_sent_now": false,
"send_block_reason": "The document must be verified before it can be sent."
},
"converted_data": {
"header": {
"document": {
"document_number": "INV-2025-001",
"document_date": "2025-10-17",
"document_type_code": "380",
"document_type_label": "Sales invoice",
"currency": "EUR",
"peppol_ready": true
},
"buyer": {
"name": "Customer Company",
"company_number": "0123456789",
"country": "BE"
},
"totals": {
"total_excl_vat": "100.00",
"total_vat": "21.00",
"total_incl_vat": "121.00"
}
},
"lines_count": 1,
"lines": [
{
"line_no": 1,
"description": "Consulting service",
"quantity": "1",
"unit_price": "100.00",
"vat_rate": "21"
}
]
}
}
Status: 400 — Invalid supplier_id, queue_guid, or conversion not found.
/pdf2peppol/confirm
• Methods:
POST
Confirm converted PDF information
Confirms that the extracted invoice or credit note information is correct. This confirmation is required before the document can be sent to Peppol.
POST
/pdf2peppol/confirm
• Rate: 300 req/min
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
supplier_id |
string | Yes | Supplier identifier. Alias accepted: apikey or api_key. | ||
queue_guid |
string | Yes | Queue GUID returned by /pdf2peppol/add. Alias: guid. | ||
confirmed |
boolean | No | 1 | Optional confirmation flag. The endpoint confirms the document if all required Peppol fields are available. |
Request examples
CURL
CURL
curl "https://api.peppox.com/pdf2peppol/confirm/?supplier_id=ed751d5a-661e-4f6e-9d74-2d7447be4a9d&queue_guid=pdf-6e9466501393cfbb32b1ec80498a1dfa"
Responses
Status: 200 — Document verification confirmed and ready to be sent.
JSON
{
"success": true,
"message": "Document verification confirmed. The document is ready to be sent to Peppol.",
"supplier_id": "ed751d5a-661e-4f6e-9d74-2d7447be4a9d",
"queue_guid": "pdf-6e9466501393cfbb32b1ec80498a1dfa",
"document_type_code": "380",
"document_type_label": "Sales invoice",
"verification_confirmed": true,
"verification_confirmed_at": "2025-10-17 15:10:00",
"send_status": "ready",
"ready_for_peppol": true,
"checks": {
"document_number": true,
"document_date": true,
"buyer_name": true,
"buyer_identifier": true,
"buyer_street": true,
"buyer_city": true,
"buyer_postal": true,
"buyer_country": true,
"document_lines": true
},
"missing_fields": []
}
Status: 400 — Document cannot be confirmed because data is missing or conversion is not ready.
/pdf2peppol/send
• Methods:
POST
Send confirmed PDF document to Peppol
Sends a confirmed PDF to Peppol. Peppox creates the invoice or credit note, adds lines, attaches the original PDF, generates the Peppol XML and starts the sending workflow. Important: after calling this endpoint, allow a delay of a few minutes because several internal processes complete and validate the document before final Peppol delivery.
POST
/pdf2peppol/send
• Rate: 300 req/min
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
supplier_id |
string | Yes | Supplier identifier. Alias accepted: apikey or api_key. | ||
queue_guid |
string | Yes | Queue GUID returned by /pdf2peppol/add. Alias: guid. |
Request examples
CURL
CURL
curl "https://api.peppox.com/pdf2peppol/send/?supplier_id=ed751d5a-661e-4f6e-9d74-2d7447be4a9d&queue_guid=pdf-6e9466501393cfbb32b1ec80498a1dfa"
Responses
Status: 200 — Document sent or already sent. Final Peppol delivery status may take a few minutes because internal processing continues after the request.
JSON
{
"success": true,
"message": "Sales invoice sent to Peppol successfully.",
"supplier_id": "ed751d5a-661e-4f6e-9d74-2d7447be4a9d",
"queue_guid": "pdf-6e9466501393cfbb32b1ec80498a1dfa",
"peppox_document_guid": "0e8b3c9d-1111-4444-9999-aabbccddeeff",
"document_type_code": "380",
"document_type_label": "Sales invoice",
"network": "production",
"send_status": "sent",
"payment_reference": "INV-2025-001",
"buyer": {
"name": "Customer Company",
"vat_id": "BE0123456789",
"company_id": "0123456789",
"street": "Customer Street 1",
"city": "Brussels",
"postal": "1000",
"country": "BE",
"phone": "+32123456789",
"email": "customer@example.com"
},
"steps": {
"document_create": "ok",
"document_lines": "ok",
"pdf_attachment": "ok",
"xml_generate": "ok"
},
"peppox_responses": {
"invoice_add": {
"ok": true,
"invoice_guid": "0e8b3c9d-1111-4444-9999-aabbccddeeff",
"status": "DRAFT"
},
"xml_generate": {
"ok": true,
"status": "XML_BUILT",
"xml_path": "created"
}
}
}
Status: 400 — Document cannot be sent. It may not be parsed, not confirmed, already sending, missing data, or Peppox API returned an error.
Status: 405 — Method not allowed.
Webhooks
No webhooks documented.
SDKs
No SDKs listed.
Error catalog
No errors defined.
Changelog
No releases yet.