E-Invoice Attachment Extraction API Reference
Extract the embedded attachments from an electronic invoice: delivery notes, timesheets, the original order, or any other supporting document the sender packed into the e-invoice. The endpoint accepts a standalone XML e-invoice (UBL 2.1, CII, or XRechnung in either syntax) or a hybrid Factur-X / ZUGFeRD PDF, collects every additional supporting document (BG-24) that carries a base64 payload (BT-125), and returns them as a single ZIP download. The attachment bytes are decoded and streamed into the archive verbatim: they are never parsed, rendered, or interpreted on the server.
https://api.invoicexml.com/v1/extract/attachments
Code Example
curl -X POST https://api.invoicexml.com/v1/extract/attachments \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "[email protected]"
Request
| Parameter | Type | Description |
|---|---|---|
| file * | binary | The invoice file to process. |
Content-Type: multipart/form-data
The source and target formats are part of the endpoint path, and everything else (syntax, declared profile, specification identifier) is read from the document itself, so there is nothing more to configure.
Headers
| Header | Value |
|---|---|
| Authorization * | Bearer YOUR_API_KEY |
| Content-Type | multipart/form-data |
Response
200 Attachment archive
Returns a ZIP archive containing every embedded attachment.
The response filename is derived from the uploaded file and the invoice number:
{original-name}-attachments-{invoice-number}.zip.
The invoice number is reduced to a file-name-safe slug and omitted when it cannot be read.
The Content-Disposition header is set to attachment for direct download.
Each ZIP entry keeps the filename the invoice declares in BT-125-2, sanitised to a flat, safe name.
Duplicate names receive a numeric suffix so no entry overwrites another on extraction, and attachments
without a declared filename are named attachment-N with an extension
derived from the declared mime code (BT-125-1).
How the E-Invoice Attachment Extraction API Works
EN 16931 e-invoices carry their supporting documents inside the invoice itself: each additional supporting document (BG-24) can embed the original file as a base64 payload (BT-125). XRechnung invoices submitted to German B2G portals, Peppol UBL invoices, and Factur-X / ZUGFeRD hybrids all use this mechanism, because the structured XML is the only artifact that travels end to end. This endpoint turns those payloads back into the original files:
Invoice ingestion
The upload is read as a standalone XML e-invoice (UBL 2.1, CII D16B, or XRechnung in either syntax), or, for a Factur-X / ZUGFeRD hybrid PDF, the embedded invoice XML is extracted first. The syntax is auto-detected; there is nothing to configure.
Attachment collection & decoding
Every BG-24 group with a base64 payload (BT-125) is collected and decoded. Decoding is a mechanical transcoding: the file content is never parsed, sniffed, rendered, or validated on the server. Documents referenced only by external URI (BT-124) are skipped by design.
ZIP delivery
The decoded files are streamed into a ZIP archive under their declared filenames (BT-125-2), sanitised and de-duplicated, and returned as application/zip with Content-Disposition: attachment, ready for archiving, accounts-payable review, or audit workflows.
Error Reference
Errors are returned as RFC 7807 ProblemDetails, using the same envelope as every other endpoint; see Error handling for the full list. The codes specific to this endpoint:
| errorCode | HTTP status | Meaning |
|---|---|---|
| 4013 | 404 | No embedded attachments. The invoice contains no BG-24 group with a BT-125 payload. Documents referenced only by external URI (BT-124) are not downloaded. |
| 4014 | 400 | Invalid attachment. An embedded BT-125 payload is not valid base64, so the invoice XML carries a corrupt attachment. The detail names the offending document reference. |
| 4006 | 400 | No embedded XML. Returned for PDF uploads that carry no embedded invoice XML, so there is no BG-24 structure to read. |
Frequently Asked Questions
Which e-invoice formats are accepted?
A standalone XML e-invoice (UBL 2.1, CII D16B, or XRechnung in either syntax) or a hybrid Factur-X / ZUGFeRD PDF. For PDFs, the embedded invoice XML is extracted first and its BG-24 groups are read; a PDF without embedded XML is rejected with errorCode 4006. Maximum file size is 20 MB.
What counts as an embedded attachment in an e-invoice?
An additional supporting document (BG-24) whose attached document (BT-125) carries a base64 payload, for example a timesheet, a delivery note, or the original order as a PDF. Documents referenced only by an external URI (BT-124) are not part of the invoice file and are deliberately not downloaded by the API; your application can follow those URLs directly.
How do I extract the attachments from an XRechnung invoice?
Upload the XRechnung XML (UBL or CII syntax) as-is. German B2G portals such as ZRE and OZG-RE transmit supporting documents inside the invoice XML rather than as separate files, so XRechnung invoices commonly carry their attachments embedded in BG-24 as base64. The endpoint decodes every embedded payload and returns the original files in one ZIP.
How do I get the attachments out of a ZUGFeRD or Factur-X PDF?
Upload the hybrid PDF directly. The API extracts the embedded factur-x.xml / zugferd-invoice.xml attachment, reads its BG-24 supporting documents, and returns their payloads as a ZIP. Note that this reads the attachments declared inside the invoice XML; PDF-level file annexes that are not referenced in the XML are not part of the EN 16931 model and are not extracted.
What happens when the invoice has no attachments?
The API returns a 404 response with errorCode 4013 (NoAttachments). This covers invoices with no BG-24 groups at all, and invoices whose supporting documents are referenced only by external URI (BT-124) without an embedded payload.
Are the attachment files opened or validated?
No. The server never parses, sniffs, or renders the attachment content. Each BT-125 payload is base64-decoded (a mechanical transcoding) and written into the ZIP byte-for-byte. If a payload is not valid base64, the API returns a 400 response with errorCode 4014 (InvalidAttachment) naming the offending document reference.
How are the files named inside the ZIP?
Each entry uses the filename declared in BT-125-2, sanitised to a flat, safe name (no directories, no path traversal, no hidden files). Duplicate names get a numeric suffix (scan.pdf, scan-2.pdf) so no entry overwrites another. An attachment without a filename becomes attachment-N, with the extension derived from the declared mime code (BT-125-1).
What is the download named?
The ZIP is served as an attachment named after your upload with an -attachments suffix and the invoice number appended: uploading invoice.pdf for invoice 2026-001 yields invoice-attachments-2026-001.zip. The invoice number is reduced to a file-name-safe slug, and omitted when it cannot be read.