---
title: "Embed ZUGFeRD invoice into an existing PDF (Base64)"
method: POST
path: "/api/zugferd/embed/base64"
tags: ["ZUGFeRD / Factur-X"]
---

# Embed ZUGFeRD invoice into an existing PDF (Base64)

`POST /api/zugferd/embed/base64`

## Request

- Base URL: `https://api.dokmatiq.com`
- URL: `https://api.dokmatiq.com/api/zugferd/embed/base64`
- Auth: API key in header `X-API-Key`

Takes a Base64-encoded PDF and invoice data, converts to PDF/A-3 and embeds a ZUGFeRD/Factur-X XML invoice. Returns the ZUGFeRD PDF as binary.

## Request body

- ZugferdEmbedRequest: Request to embed a ZUGFeRD invoice into a Base64-encoded PDF
  - `pdfBase64` string, required: Base64-encoded PDF
  - `invoice` InvoiceData, required: ZUGFeRD/Factur-X invoice data to embed in a PDF
    - `profile` 'MINIMUM' | 'BASICWL' | 'BASIC' | 'EN16931' | 'EXTENDED' | 'XRECHNUNG': ZUGFeRD profile
    - `number` string, required: Invoice number
    - `date` string, required: Invoice date (ISO format)
    - `dueDate` string: Due date (ISO format)
    - `currency` string: Currency code (ISO 4217)
    - `seller` Party, required: Trade party (seller or buyer)
      - `name` string, required: Company or person name
      - `street` string, required: Street address
      - `zip` string, required: ZIP / postal code
      - `city` string, required: City
      - `country` string: Country code (ISO 3166-1 alpha-2)
      - `vatId` string: VAT identification number
      - `email` string: Email address
      - `phone` string: Phone number
    - `buyer` Party, required: Trade party (seller or buyer)
      - `name` string, required: Company or person name
      - `street` string, required: Street address
      - `zip` string, required: ZIP / postal code
      - `city` string, required: City
      - `country` string: Country code (ISO 3166-1 alpha-2)
      - `vatId` string: VAT identification number
      - `email` string: Email address
      - `phone` string: Phone number
    - `items` InvoiceItem[], required: Invoice line items
      - `description` string, required: Item description
      - `quantity` number, required: Quantity
      - `unit` 'HUR' | 'C62' | 'KGM' | 'MTR' | 'LTR' | 'DAY': Unit code (UN/ECE Rec 20)
      - `unitPrice` number, required: Unit price (net)
      - `vatRate` number, required: VAT rate in percent
    - `paymentTerms` string: Payment terms description
    - `bankAccount` BankAccount: Bank account details for payment
      - `iban` string, required: IBAN
      - `bic` string: BIC/SWIFT code
      - `accountHolder` string: Account holder name
    - `referenceNumber` string: Reference number (e.g. Leitweg-ID for XRechnung)
    - `buyerReference` string: Buyer reference (Leitweg-ID), required for XRechnung
    - `invoiceTypeCode` '380' | '381' | '384' | '389': Invoice type code (UN/CEFACT 1001)
    - `sellerTaxNumber` string: Seller tax number (Steuernummer, alternative to VAT ID)
    - `paymentMeansCode` string: Payment means code (UN/CEFACT 4461)
    - `xrechnungFormat` 'CII' | 'UBL': XRechnung output format (CII or UBL)

## Response `200`

ZUGFeRD PDF

## Other responses

- `400`: Invalid input
- `500`: Embedding failed

---

[API](https://skmtc.dev/dokmatiq/apis/docgen-api.md) · [All operations](https://skmtc.dev/dokmatiq/apis/docgen-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dokmatiq/apis/docgen-api/revisions/3fa1a922764d?raw)