Embed CII XML in PDF using REST-API
Combine a user-supplied PDF and a user-supplied UN/CEFACT Cross Industry Invoice (CII) XML into a single Factur-X / ZUGFeRD compliant PDF/A-3 with the XML embedded as the factur-x.xml attachment. Useful when you already have a rendered invoice PDF (from your accounting system, template engine, or any source) plus a separate EN 16931 XML and want the hybrid container produced for you without going through the full /v1/create flow.
https://api.invoicexml.com/v1/embed/xml
Code Example
curl -X POST https://api.invoicexml.com/v1/embed/xml \ -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
What does this endpoint do that /v1/create does not?
/v1/create generates the entire hybrid PDF from a JSON invoice document, rendering both the visual layer and the XML. /v1/embed/xml leaves the visual layer to you, you supply your own already rendered PDF and your own CII XML, and the API only handles PDF/A-3 promotion and XML attachment. Use it when you already have a designed invoice PDF and want to keep its exact layout, fonts, and branding.
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 output Factur-X or ZUGFeRD?
Both. Factur-X and ZUGFeRD 2.x use an identical PDF/A-3 + CII XML container, the only differences are the French vs. German branding around it. The embedded attachment is named factur-x.xml, which is accepted by every conformant reader on both sides of the border.
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/xml 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.