Extraction fields

Extraction response shape

Extraction responses are keyed by normalized field name. Each field contains a system-ready value, optional candidates considered for review, and optional provenance for the selected value. Candidate provenance is not included.

{
  "data": {
    "type": {
      "value": "invoice",
      "candidates": ["Invoice"]
    },
    "document_number": {
      "value": "RE-2026-1048",
      "candidates": ["RE-2026-1048"],
      "provenance": {
        "method": "structured_invoice",
        "source": "pdf_embedded_xml",
        "derived_from": [],
        "transforms": []
      }
    },
    "issue_date": {
      "value": "2026-05-10",
      "candidates": ["10 May 2026"]
    },
    "sender_name": {
      "value": "Meyer Supply GmbH",
      "candidates": ["Meyer Supply GmbH"]
    },
    "recipient_name": {
      "value": "Northwind Operations Ltd.",
      "candidates": ["Northwind Operations Ltd."]
    },
    "currency": {
      "value": "EUR",
      "candidates": ["EUR"]
    },
    "gross_amount": {
      "value": "1079.50",
      "candidates": ["Amount due EUR 1,079.50"]
    },
    "tax_breakdowns": {
      "value": [
        {
          "taxable_amount": "1079.50",
          "tax_amount": "0.00",
          "tax_rate": "0.00",
          "taxability": "taxable",
          "tax_collection_mechanism": "reverse_charge",
          "tax_exemption_reason": "Intra-EU B2B reverse charge"
        }
      ],
      "candidates": ["Reverse charge applies under Article 196 VAT Directive"]
    }
  }
}

Winning-value provenance

method is one of structured_invoice, ai, deterministic, structured_markup, email_envelope, derived, or unknown. source uses a bounded category such as xml, pdf_embedded_xml, email_attachment_xml, document_text, pdf_text, ocr_text, email_header, or email_body. Broader categories such as mixed are used when a more precise source cannot be attributed safely.

A semantically derived value identifies its inputs without copying their contents. For example, a BIC calculated from an extracted IBAN reports method: "derived", derived_from: ["iban"], and a bounded transform identifier. Normalization alone preserves the original extraction method. Read latest_extraction_run.provenance_summary for method counts across all selected non-null fields; strategies_used remains separate processing metadata. The summary is null when the run has no persisted automatic winning-field provenance, including analysis, validation, in-progress, legacy, and reviewed-profile results.

E-invoice validation coverage

The validation claim is reported per run in quality.structured.validation_scope. xml_profile_conformance applies only to Standard XRechnung 3.0 and Extension XRechnung 3.0 in the named XML syntax, profile, scenario, and persisted ruleset version. structural_and_business reports deterministic parser, structural, business, and arithmetic checks without claiming complete official profile conformance.

For a PDF with embedded XML, the XML result and visible invoice evidence are assessed separately. In validation mode, bounded rendered OCR supplies the visible evidence; a searchable or hidden native text layer cannot establish a passing result. A valid XML profile can therefore retain validation_status: "valid" while assessment: "fail" reports a PDF/XML conflict. Multiple recognized invoice XML attachments return multiple_embedded_invoice_xml_attachments as an indeterminate result instead of selecting one. No current result claims complete PDF/A or e-invoice container conformance, and none is a statement of legal validity.

Extension XRechnung 3.0

Exdata validates the original UBL or CII for Extension XRechnung 3.0 with the matching pinned official KoSIT scenario, without rewriting the source syntax. Support is limited to invoices that declare the exact profile urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0#conformant#urn:xeinkauf.de:kosit:extension:xrechnung_3.0 and pass the profile and deterministic mapping checks. The exact CVD profile is additionally supported in CII syntax through its pinned CVD scenario, but its reported scope is structural_and_business; UBL CVD is not claimed as supported. An invalid invoice or an unknown or unsupported profile fails closed.

In extraction mode, every supported e-invoice receives one human-readable HTML invoice visualization in CII, UBL, and ZUGFeRD 1.0 COMFORT syntax, so the same invoice layout is returned regardless of the source format. Locally validated Extension XRechnung 3.0 invoices additionally keep their source-ordered recursive invoice-line view. For exceptionally large line sets or repeatable review sections, the affected content is shown as a clearly labelled bounded prefix so browser rendering remains safe; the original XML remains unchanged. This HTML file is the canonical preview; the accompanying JPEG is only a representative thumbnail and visual fallback. Other convertible e-invoices are transformed to HTML, while remaining safe XML uses a pretty-printed XML fallback.

Accepted invoices map into the document-level v1 fields. For the UBL Extension path, these include type, document_number, date, issue_date, period_start, period_end, currency, net_amount, gross_amount, tax_amount, seller and recipient identity, address, country, tax and VAT fields, customer_id, payment_due_date, one unambiguous payee iban and bic, normalized tax breakdown and classification fields, and note. Recursive line hierarchy, embedded attachment metadata, and third-party payment rows feed the HTML visualization but are not returned as v1 extraction fields; exceptionally large line sets or repeatable review sections are shown as clearly labelled source-order prefixes. Multiple ambiguous payee accounts remain validation-only and leave the singular iban and bic fields null.

For the UBL Extension path, net_amount is UBL TaxExclusiveAmount and gross_amount is the tax-inclusive invoice total, UBL TaxInclusiveAmount (BT-112). gross_amount is not the remaining PayableAmount after prepaid or third-party payment allocation.

ZUGFeRD 1.0 COMFORT

Exdata supports invoices that declare the exact profile urn:ferd:CrossIndustryDocument:invoice:1p0:comfort and TypeCode 380 or 84. The published tax TypeCodes VAT, ZF_INSURANCE_TAX (insurance tax), and AAJ (second-hand-parts tax) are supported. The original XML must pass its ZUGFeRD 1.0 XSD, Schematron constraints, and arithmetic validation. The reported scope is structural_and_business, not complete XML profile conformance. ZUGFeRD 1.0 BASIC, EXTENDED, other document or tax codes, invalid, and unknown profiles fail closed with unsupported_structured_invoice.

Accepted COMFORT invoices map validated document, party, payment, amount, tax, billing-period, and note values into the document-level v1 fields. gross_amount is GrandTotalAmount; the optional DuePayableAmount is used only as validation and linkage evidence. The same rules apply to XML embedded in a PDF; embedded values become authoritative only when the visible invoice corroborates its critical identity and amounts without conflicts. XML email attachments use the same validation path.

Normalized values

Use value for automation, candidates for review, and provenance to route or audit the selected value by extraction path. The same response shape is used for PDFs, images, office documents, email files, XML/e-invoices, and structured source files.

Tax breakdown rows

tax_breakdowns.value is null or an array. Each row represents one visible tax rate or tax category from the document. Use rows when your system needs posting, VAT/GST handling, reverse-charge treatment, or audit trails.

{
  "tax_breakdowns": {
    "value": [
      {
        "taxable_amount": "1079.50",
        "tax_amount": "0.00",
        "tax_rate": "0.00",
        "taxability": "taxable",
        "tax_collection_mechanism": "reverse_charge",
        "tax_exemption_reason": "Intra-EU B2B reverse charge"
      }
    ],
    "candidates": ["Reverse charge applies under Article 196 VAT Directive"]
  }
}

Field metadata

Every standard extraction key below can appear in the data object. Use the field name as the stable mapping key, candidates for value review, and provenance for the origin of the selected value.

Document fields

Field reference for the keys available in document extraction. A field can be present with null when it is not visible or not applicable to the uploaded document.

Identity and dates

Amounts and payment

Tax classification

Parties and addresses

Contact and notes

Email fields

These fields are extracted from EML and MSG uploads. When no usable financial attachment is present, shared fields describe the email itself: type is email, title comes from the subject, date comes from the email header, and email parties can populate sender_name and recipient_name.

When a supported attachment is selected, its financial evidence is authoritative for shared document fields, including type, title, date, issue_date, sender_name, and recipient_name. The envelope stays available through from, from_email, to, to_email, subject, and email_date. Exdata selects one primary financial attachment for one result. Supported e-invoice XML is preferred when its profile, structural constraints, and arithmetic business invariants pass. When an email also contains a PDF, critical XML fields must link to that human-readable representation without conflicts before the XML becomes authoritative; otherwise the PDF is used when it remains readable. Other document candidates are surfaced through degraded quality metadata rather than merged into one record.