CII Validation API Reference

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

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.

French mandate rules on demand

To check the file against the French CTC mandate as well, add the optional rules form field with br-fr. The BR-FR Flux 2 rules, the same rule set the Plateformes Agréées and the PPF apply to every domestic French invoice, then run on top of the rule set the document's declared profile selects:

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

The base verdict is unchanged: profile detection, data.profile and data.customizationId all work exactly as without the field, and the mandate findings appear in the same errors array with rule ids starting with BR-FR. Documents declaring the MINIMUM or BASIC WL profile are rejected with a 400: the mandate reads those header-only subsets as booking aids, not invoices. A document declaring the EXTENDED-CTC-FR profile already runs these rules by default, so the field adds nothing there.

Findings in German or French

Every finding carries a plain-language message you can show to your users. It is written in English unless the optional validationLanguage form field asks for German (de) or French (fr):

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

The verdict is unchanged, and so are rule, layer, btCodes, fields and raw, so keep matching on the rule id and field paths, never on the message text. Rules without a curated German or French wording, such as the CII-SR and UBL-SR syntax rules, keep the rule set's English message. Localized error messages has the details.

Request

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

Response

{
  "valid": true,
  "detail": "Your invoice is cii 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.
  ]
}

{
  "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": "Enter the specification identifier, which names the standard the invoice follows, for example urn:cen.eu:en16931:2017.",
      "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": "Enter the seller 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-24",
      "layer": "en16931",
      "line": 2,
      "message": "Enter the net amount of this line.",
      "btCodes": ["BT-131"],
      "fields": ["lines[1].lineNetAmount"],
      "raw": "[BR-24] EN16931: Each Invoice line shall have an Invoice line net amount. (at /*:CrossIndustryInvoice/*:SupplyChainTradeTransaction/*:IncludedSupplyChainTradeLineItem[2])"
    }
  ],
  "warnings": [
    {
      "rule": "BR-CL-01",
      "layer": "en16931",
      "line": null,
      "message": "Choose an invoice type code from the UNTDID 1001 list, for example 380 (invoice) or 381 (credit note).",
      "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": [{ "rule": "BR-06", "message": "Enter the seller 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:

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.

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:

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": []
}

Useful resources

Companion material for integrating against the API.