XRechnung Validation API Reference

Technical reference for validating XRechnung documents in either syntax. The endpoint detects whether the upload is CII or UBL, runs the matching XSD, the EN 16931 Schematron, and the XRechnung CIUS rules from the KoSIT Schematron in force (release 2.5.0 for specification 3.0), the same rule set German government portals such as ZRE and OZG-RE enforce. Findings are returned as structured JSON.

POST https://api.invoicexml.com/v1/validate/xrechnung

Code Example

curl -X POST https://api.invoicexml.com/v1/validate/xrechnung \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

The invoice profile and version are detected automatically from the uploaded file, so you never need to pass them. The detected values are returned in the response.

Try it out online, no coding required

Upload an invoice and get a full compliance report instantly, right in your browser.

Try It Online

Request

Parameter	Type	Description
file *	binary	The invoice file to validate. Accepted format: standalone XRechnung XML document (CII or UBL syntax). PDFs are not accepted on this endpoint.

Content-Type: multipart/form-data

That is the whole request. The syntax and the conformance profile (Peppol BIS, XRechnung, NLCIUS, PINT, or the Factur-X/ZUGFeRD profile ladder) are detected automatically from the document's specification identifier (BT-24), the matching rule set is applied, and the response reports what was validated against in data.profile and data.customizationId.

Headers

Header	Value
Authorization *	Bearer YOUR_API_KEY
Content-Type	multipart/form-data

Response

200 Valid invoice

The invoice passed every check. valid is true and errors is empty.

Content-Type: application/json

{
  "valid": true,
  "detail": "Your invoice is xrechnung compliant and meets the EN 16931 specifications.",
  "data": {
    "schemaValid": true,
    "schematronValid": true,
    "conformanceLevel": "EN16931",
    "profile": "en16931",
    "customizationId": "urn:cen.eu:en16931:2017"
  },
  "errors": [],
  "warnings": [],
  "report": [
    { "code": "BT-1", "name": "Invoice number", "section": "header", "path": "invoiceNumber", "value": "INV-2026-001", "isValid": true, "errors": [], "warnings": [] },
    { "code": "BT-2", "name": "Invoice issue date", "section": "header", "path": "issueDate", "value": "2026-05-19", "isValid": true, "errors": [], "warnings": [] }
    // ... one row per EN 16931 Business Term. See the Validation Report section below.
  ]
}

200 Invalid invoice

Validation still returns HTTP 200. valid is false and the findings are in the errors array.

{
  "valid": false,
  "detail": "Validation failed with 3 error(s)",
  "data": {
    "schemaValid": true,
    "schematronValid": false,
    "conformanceLevel": "EN16931",
    "profile": "en16931",
    "customizationId": "urn:cen.eu:en16931:2017"
  },
  "errors": [
    {
      "rule": "BR-01",
      "layer": "en16931",
      "line": null,
      "message": "The invoice is missing a specification identifier (BT-24).",
      "btCodes": ["BT-24"],
      "fields": ["specificationId"],
      "raw": "[BR-01] EN16931: An invoice shall have a specification identifier. (at /*:CrossIndustryInvoice)"
    },
    {
      "rule": "BR-06",
      "layer": "en16931",
      "line": null,
      "message": "The seller must have a name (BT-27). Add the seller's name.",
      "btCodes": ["BT-27"],
      "fields": ["seller.name"],
      "raw": "[BR-06] EN16931: An invoice shall contain the seller name. (at /*:CrossIndustryInvoice/*:SupplyChainTradeTransaction/*:ApplicableHeaderTradeAgreement/*:SellerTradeParty)"
    },
    {
      "rule": "BR-23",
      "layer": "en16931",
      "line": 2,
      "message": "Line item 2: Each invoice line must have a net amount.",
      "btCodes": ["BT-131"],
      "fields": ["lines[1].lineNetAmount"],
      "raw": "[BR-23] EN16931: An Invoice line shall have an Invoice line net amount. (at /*:CrossIndustryInvoice/*:SupplyChainTradeTransaction/*:IncludedSupplyChainTradeLineItem[2])"
    }
  ],
  "warnings": [
    {
      "rule": "BR-CL-01",
      "layer": "en16931",
      "line": null,
      "message": "The document type code should use a recognised UNTDID 1001 value.",
      "btCodes": ["BT-3"],
      "fields": ["typeCode"],
      "raw": "[BR-CL-01] EN16931-codelist: The document type code MUST be coded according to UNTDID 1001. (at /*:CrossIndustryInvoice/*:ExchangedDocument/*:TypeCode)"
    }
  ],
  "report": [
    // ... one row per EN 16931 Business Term. See the Validation Report section below.
    { "code": "BT-27", "name": "Seller name", "section": "seller", "path": "seller.name", "value": null, "isValid": false, "errors": ["The seller must have a name (BT-27). Add the seller's name."], "warnings": [] }
  ]
}

Error Reference

When an invoice fails validation, the top-level errors array contains one "finding" object per violated business rule. The warnings array uses the same finding shape for non-blocking advisory issues that do not cause valid to become false. On a valid invoice errors is an empty array, while warnings may still contain entries.

Each finding object carries both a friendly, user-facing message and the verbatim technical raw validator output. Each object contains:

Field	Type	Description
rule	string	The business rule identifier (e.g. `BR-01`, `BR-DE-15`).
layer	string	The validation layer that produced the finding: `xsd` (XML schema), `en16931` (EN 16931 core business rules), or `cius` (profile overlay rules such as Peppol BIS or BR-DE). The PDF embedding findings (`PDF-EMBED`, `PDF-EMBED-SYNTAX`) report upload problems rather than rule violations and omit this field.
line	int \| null	The 1-based invoice line item number the error relates to, or `null` when the error applies to the document level.
message	string	A plain-language explanation of the violation, suitable for displaying directly to end users.
btCodes	string[]	The EN 16931 Business Term / Business Group codes the rule references (e.g. `["BT-27"]`). Empty when the rule maps to no specific term.
fields	string[]	Dotted JSON paths into the invoice document that the error applies to (e.g. `["seller.name"]`, `["lines[1].lineNetAmount"]`). Derived from `btCodes`; line-scoped paths carry a zero-based `lines[N]` index. Empty when no field could be resolved.
raw	string	The verbatim technical message from the validator, including the rule id, layer and XPath location.

The fields array is intended for client UIs: each path matches the request body structure, so a front-end form can map a validation error straight onto the input that produced it. Highlight that input, attach message beside it, and the user can correct the exact field without reading the raw rule text. Line-scoped paths use a zero-based index (lines[1] is the second line item) to match JavaScript array indexing.

Status	Meaning	Action
200	Validation completed. Check `valid` to determine compliance.	If `valid` is `false`, inspect the `errors` array.
401	Missing or invalid API key.	Check the `Authorization` header.
422	File is not a valid PDF or XML document.	Ensure you are uploading a supported file format.

Validation Report

Every response, whether the invoice is valid or not, includes a top-level report array. It contains one row per EN 16931 Business Term present on the parsed invoice, pairing each term with its current value and a pass/fail flag. This gives a complete, field-by-field picture of the document, not just the rules that failed, which is useful for rendering a compliance table or a side-by-side review UI. The snippets above show report truncated to a couple of rows to avoid repeating the full structure.

Each row in the array is an object with the following fields:

Field	Type	Description
code	string	The EN 16931 Business Term code (e.g. `BT-1`).
name	string	The human-readable name of the Business Term.
section	string	Logical grouping for display: `header`, `seller`, `buyer`, `lines`, `payment`, `totals`, or `tax`.
path	string	Dotted JSON path into the invoice document (e.g. `lines[0].priceDetails.netPrice`). Same path scheme as `errors[].fields`.
value	string \| null	The current value of the term as a string, or `null` when the field is absent.
isValid	boolean	`true` when this row has no errors, otherwise `false`.
errors	string[]	Every error message referencing this Business Term; empty when none.
warnings	string[]	Every warning message referencing this Business Term; empty when none.

A single report row looks like this:

{
  "code": "BT-1",
  "name": "Invoice number",
  "section": "header",
  "path": "invoiceNumber",
  "value": "INV-2026-001",
  "isValid": true,
  "errors": [],
  "warnings": []
}

Frequently Asked Questions

Which rule sets does POST /v1/validate/xrechnung run?

Three layers, each tagged on its findings: the XSD for the detected syntax (UBL 2.1 or CII D16B) reported as layer xsd, the EN 16931 core Schematron reported as layer en16931, and the German BR-DE rules from the KoSIT XRechnung Schematron (release 2.5.0, specification 3.0) reported as layer cius.

Does this endpoint follow the profile the document declares?

No, and that is the difference from POST /v1/validate/ubl and /v1/validate/cii. This endpoint always applies the XRechnung rule set, so data.profile is always xrechnung, while data.customizationId echoes whatever BT-24 declares. A declared identifier that does not match the XRechnung specification is flagged by the CIUS rules themselves.

Are XRechnung 2.x documents still valid?

No. XRechnung 3.0 has been the version in force since February 2024, and the validator applies the current 3.0 rules to every upload. A document declaring a retired 2.x identifier is reported as non-compliant; re-issue it as 3.0. The version lifecycle for created documents is covered under options.version on POST /v1/create/xrechnung.

Is the Leitweg-ID checked?

Yes. XRechnung requires the Leitweg-ID in the buyer reference (BT-10) for B2G invoices, enforced by rule BR-DE-15. A missing buyer reference comes back as a cius-layer error with a friendly message and a fields path pointing at the buyer reference input.

Can I validate a ZUGFeRD PDF with the XRechnung reference profile here?

Not on this endpoint, it accepts XML only and rejects other uploads with HTTP 422. Upload the hybrid PDF to POST /v1/validate/zugferd or /v1/validate/facturx instead: the embedded xrechnung.xml attachment is recognized and the XML is routed to the same KoSIT rules automatically.