---
title: "POST /v1/validate/ubl"
method: POST
path: "/v1/validate/ubl"
tags: ["Validate"]
---

# POST /v1/validate/ubl

`POST /v1/validate/ubl`

## Request

- Base URL: `https://api.invoicexml.com`
- URL: `https://api.invoicexml.com/v1/validate/ubl`
- Auth: none declared

## Response `200`

OK

- ValidationResponse: The JSON verdict every `/v1/validate/*` endpoint answers with on HTTP 200, whether the document passed or failed (the `/report` siblings answer with a PDF instead).
  - `valid` boolean, required: `true` when the document passed every fatal rule.
  - `detail` string, required: One sentence summarising the verdict.
  - `data` ValidationResponseData, required: Outcome per validation layer plus the profile the document was checked against. Which fields are present depends on the endpoint and on how far validation got.
    - `hasEmbeddedXml` boolean, nullable: Hybrid PDF endpoints only (`facturx`, `zugferd`, `order-x`): whether the PDF carried an invoice XML attachment. When `false`, no other field is present.
    - `schemaValid` boolean, nullable: Whether the XML passed the XSD schema layer.
    - `schematronValid` boolean, nullable: Whether the XML passed the EN 16931 and profile (CIUS) business rules.
    - `conformanceLevel` string, nullable: The standard validated against: `EN16931`, `UBL 2.1`, `XRechnung` or `Order-X`.
    - `profile` string, nullable: Slug of the profile whose rule set ran (for example `peppol-bis-3`, `xrechnung`, `facturx-basic`). `null` when the document declares no profile this validator has dedicated rules for.
    - `customizationId` string, nullable: The specification identifier (BT-24) the document declares, verbatim.
  - `errors` ValidationFinding[], required: Fatal findings. Empty when Valid is `true`.
    - `rule` string, nullable, required: Identifier of the rule that fired (for example `BR-CO-15`, `PEPPOL-EN16931-R010`, `PDF-EMBED`). `null` for a request model finding that reports no rule.
    - `layer` string, nullable, required: Validation layer the finding came from: `xsd`, `en16931` or `cius`. `null` for findings outside the XML validation pipeline.
    - `line` integer, nullable, required: 1-based invoice line the finding refers to, or `null` for document-level findings.
    - `message` string, required: Human-readable explanation of the finding and how to fix it, in the language the request asked for with `validationLanguage` (`en`, `de` or `fr`; English by default). The text of a rule that has no curated message stays in the rule set's own wording.
    - `btCodes` string[], required: EN 16931 Business Terms involved (for example `BT-31`). Empty when the rule maps to none.
    - `fields` string[], required: Dotted paths into the invoice JSON model (for example `seller.vatIdentifier`, `lines[0].quantity`). Empty when the rule maps to none.
    - `raw` string, nullable, required: The validator's verbatim output line for the finding, whatever the `validationLanguage`. `null` when there is none.
  - `warnings` ValidationFinding[], required: Non-blocking findings (Schematron warnings and advisories such as an unrecognised profile). Never affect the verdict.
    - `rule` string, nullable, required: Identifier of the rule that fired (for example `BR-CO-15`, `PEPPOL-EN16931-R010`, `PDF-EMBED`). `null` for a request model finding that reports no rule.
    - `layer` string, nullable, required: Validation layer the finding came from: `xsd`, `en16931` or `cius`. `null` for findings outside the XML validation pipeline.
    - `line` integer, nullable, required: 1-based invoice line the finding refers to, or `null` for document-level findings.
    - `message` string, required: Human-readable explanation of the finding and how to fix it, in the language the request asked for with `validationLanguage` (`en`, `de` or `fr`; English by default). The text of a rule that has no curated message stays in the rule set's own wording.
    - `btCodes` string[], required: EN 16931 Business Terms involved (for example `BT-31`). Empty when the rule maps to none.
    - `fields` string[], required: Dotted paths into the invoice JSON model (for example `seller.vatIdentifier`, `lines[0].quantity`). Empty when the rule maps to none.
    - `raw` string, nullable, required: The validator's verbatim output line for the finding, whatever the `validationLanguage`. `null` when there is none.
  - `report` InvoiceReportRow[], nullable: The invoice's Business Terms (BT-x) with their values and the findings attached to each, for field-level display. `null` when the document could not be parsed into the invoice model. Absent on `/v1/validate/order-x` and when no invoice XML could be read (a PDF without an embedded XML, or one embedding the wrong syntax).
    - `code` string, required
    - `name` string, required
    - `section` string, required
    - `path` string, required
    - `value` string, nullable, required
    - `isValid` boolean, required
    - `errors` InvoiceReportFinding[], required
      - `rule` string, required
      - `message` string, required
    - `warnings` InvoiceReportFinding[], required
      - `rule` string, required
      - `message` string, required

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `413`: Payload Too Large
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/invoicexml/apis/invoicexml-api.md) · [All operations](https://skmtc.dev/invoicexml/apis/invoicexml-api/llms.txt) · [OpenAPI document](https://skmtc.dev/invoicexml/apis/invoicexml-api/revisions/3181e160f14e?raw)