Embed CII XML in PDF as Factur-X using REST-API
Combine a user-supplied PDF and a user-supplied UN/CEFACT Cross Industry Invoice (CII) XML into a single Factur-X compliant PDF/A-3 with the XML embedded as the factur-x.xml attachment. The output PDF/A-3 carries Factur-X-branded XMP metadata (fx: namespace, urn:factur-x.eu:1p0:* conformance URN). Use it 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/facturx
Code Example
curl -X POST https://api.invoicexml.com/v1/embed/facturx \ -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/facturx 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.
How does this differ from /v1/embed/zugferd?
Both endpoints produce a hybrid PDF/A-3 with the same factur-x.xml attachment. The difference is the XMP metadata of the container: /v1/embed/facturx writes the Factur-X namespace and conformance URN (fx:, urn:factur-x.eu:1p0:*), while /v1/embed/zugferd writes the ZUGFeRD namespace and conformance URN (zf:, urn:zugferd:*). Pick the one that matches the brand identifier your downstream consumer checks.
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/facturx 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/facturx 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.