ZUGFeRD Parsing

The ZUGFeRD endpoint is available on Pro and Business. It reads embedded XML from a PDF and returns the same extraction response envelope as the standard extraction endpoints.

Use POST /v1/extract/zugferd for hybrid PDFs with supported embedded XML attachments.

For the AP document response envelope, standalone XML uploads, or Business-only XRechnung and Peppol parsing, use POST /v1/documents/extract/file instead. In that API, document_type stays the business document type such as invoice or credit_note, while source_format identifies the structured format such as zugferd, factur_x, xrechnung, or peppol_bis_billing.

Supported Attachments

The parser looks for known embedded XML filenames:

If no supported XML attachment can be read, the request returns an application error.

Plan Gating and Fallback

Calling this endpoint below Pro returns 402 with feature_not_in_plan. If the user is not on Pro or Business, send the same PDF to POST /v1/extract/file instead. The standard file endpoint uses OCR/extraction and does not require embedded XML.

Request

The locale hint is a query parameter.

curl -X POST "https://api.parsurai.com/v1/extract/zugferd?locale=auto" \
  -H "X-API-Key: $PARSURAI_API_KEY" \
  -F "file=@zugferd-invoice.pdf"

Response

{
  "invoice_id": "2f7d7f8a-32fb-4a7c-a3b1-53b61b64252f",
  "invoice": {
    "document_type": "invoice",
    "vendor": {
      "name": "Muster GmbH",
      "address": null,
      "email": null,
      "phone": null,
      "tax_id": "DE123456789",
      "iban": null,
      "bank_name": null
    },
    "buyer": {
      "name": "Buyer GmbH",
      "address": null,
      "email": null,
      "phone": null,
      "tax_id": "DE987654321",
      "iban": null,
      "bank_name": null
    },
    "invoice_number": "2026-DE-0042",
    "issue_date": "2026-06-01",
    "due_date": "2026-07-01",
    "billing_period_start": null,
    "billing_period_end": null,
    "reference_numbers": [],
    "line_items": [],
    "subtotal": 2500.0,
    "discount_total": null,
    "tax_breakdown": [
      {
        "tax_type": "VAT",
        "rate": 0.19,
        "taxable_amount": 2500.0,
        "tax_amount": 475.0
      }
    ],
    "tax_total": 475.0,
    "total_amount": 2975.0,
    "amount_paid": null,
    "amount_due": 2975.0,
    "currency": "EUR",
    "payment_terms": null,
    "payment_instructions": null,
    "locale": "de",
    "confidence": 1.0,
    "field_confidence": {},
    "notes": []
  },
  "duplicate_risk": null,
  "anomalies": [],
  "confidence_low": false,
  "field_bboxes": null
}