Embed CII XML in PDF as ZUGFeRD using REST-API
Combine a user-supplied PDF and a user-supplied UN/CEFACT Cross Industry Invoice (CII) XML into a single ZUGFeRD 2.x compliant PDF/A-3 with the XML embedded as the factur-x.xml attachment (per the modern ZUGFeRD / Factur-X convergence on the attachment filename). The output PDF/A-3 carries ZUGFeRD-branded XMP metadata (zf: namespace, urn:zugferd:* conformance URN), the form expected by German B2B and B2G readers.
https://api.invoicexml.com/v1/embed/zugferd
Code Example
curl -X POST https://api.invoicexml.com/v1/embed/zugferd \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "[email protected]" \ -F "[email protected]"
Request
| Parameter | Type | Description |
|---|---|---|
| pdf * | binary | The base PDF to embed the XML into. Any standard PDF is accepted, it will be promoted to PDF/A-3 by the embedder. |
| xml * | binary | A UN/CEFACT Cross Industry Invoice (CII) XML document. The root element must be CrossIndustryInvoice in the CII D16B namespace, UBL documents are not accepted. |
Content-Type: multipart/form-data
Headers
| Header | Value |
|---|---|
| Authorization * | Bearer YOUR_API_KEY |
| Content-Type | multipart/form-data |
Response
200 Embedded PDF
Returns the embedded PDF/A-3 as a binary file.
The response filename is derived from the uploaded PDF: {original-name}-facturx.pdf.
The Content-Disposition header is set to attachment for direct download.
How the Embed XML API Works
The API takes two uploads and produces a single hybrid PDF/A-3 ready for B2B exchange:
Receive the PDF and the CII XML
Upload your already rendered invoice PDF (from your accounting system, template engine, or any source) together with the matching UN/CEFACT Cross Industry Invoice XML. The API shape-checks the XML root, only CrossIndustryInvoice documents are accepted. UBL invoices are rejected, convert them with /v1/convert/ubl/to/cii first.
Promote the PDF to PDF/A-3 and embed the XML
The base PDF is converted to PDF/A-3 in-place, then the XML is attached as the factur-x.xml attachment with the metadata required by ZUGFeRD / Factur-X (relationship, MIME type, AFRelationship). The result is a single hybrid container that is both human-readable and machine-processable.
Return the embedded PDF
The API response is the new PDF/A-3 streamed back as application/pdf. The filename is derived from the uploaded PDF: {original-name}-facturx.pdf.
Frequently Asked Questions
How does this differ from /v1/embed/facturx?
Both endpoints produce a hybrid PDF/A-3 with an identical factur-x.xml attachment. The difference lives in the XMP metadata: /v1/embed/zugferd advertises the ZUGFeRD namespace (zf:) and conformance URN (urn:zugferd:*), while /v1/embed/facturx advertises the Factur-X namespace (fx:) and conformance URN (urn:factur-x.eu:1p0:*). Use the endpoint that matches the brand your downstream consumer expects.
Which ZUGFeRD profile is written into the metadata?
The profile is parsed from the GuidelineSpecifiedDocumentContextParameter/ID element of the input XML, so the XMP advertises the conformance level (Minimum, Basic WL, Basic, EN 16931 / Comfort, Extended) actually present in your CII document, never a hardcoded default.
Which XML formats are accepted?
Only UN/CEFACT Cross Industry Invoice (CII) D16B XML, the root element must be <CrossIndustryInvoice> in the CII namespace. UBL documents are rejected with a 400 response. If your invoice is in UBL syntax, convert it first using POST /v1/convert/ubl/to/cii.
Is the source PDF validated as PDF/A?
Any standard PDF is accepted. The embedder promotes the container to PDF/A-3 in-place, adding the metadata, output intent, and document structure required for archival conformance. The visual content is preserved as-is.
Is the XML validated against EN 16931 rules?
No. /v1/embed/zugferd only shape-checks the XML root and embeds it. If you want a full Schematron validation pass against EN 16931, run the XML through POST /v1/validate/cii (or POST /v1/validate/zugferd on the output PDF) before or after embedding.
What is the maximum file size?
20 MB per file. PDFs are typically the larger of the two uploads, CII XML files are usually a few kilobytes.
Is the input data stored?
No. Both files are processed entirely in memory and discarded immediately after the embedded PDF is returned. Nothing is written to disk or retained server-side.