Validate · SUMU API Docs

Runs the full Oman rule set against a UBL document without sending anything. Free of rate-limit cost against your send quota, and safe to call as often as you like — use it in your test suite or as a pre-flight check in CI before going live.

POST/v1/api/documents/validate

synchronous

Field	Type		Description
document	string	required	The UBL XML as a JSON string
profile	string	optional	Assert which profile you expect. If it disagrees with the document you get 400 PROFILE_MISMATCH — useful for catching a generator emitting the wrong CustomizationID

Response fields

Field	Type		Description
valid	boolean	—	true when there are no errors. Warnings don't make a document invalid
profile	string	—	Which rule set was resolved from the document
issues[].severity	enum	—	error blocks sending · warning doesn't · info is advisory
issues[].code	string	—	The Oman rule identifier, e.g. IBR-019-OM. Quotable against the published rule text
issues[].location	string	—	XPath to the element at fault

A 200 means the document was checked, not that it passed — read valid. Failing this returns the same SCHEMATRON_INVALID issue shape as Create an invoice's 422 response, so the same handling code works for both.

REQUEST

cURL

curl -X POST https://api.joinsumu.com/v1/api/documents/validate \
-H "X-API-Key: sumu_live_..." \
-H "Content-Type: application/json" \
-d '{
  "document": "<?xml version=\"1.0\"?><Invoice>...</Invoice>"
}'

RESPONSE200 OK

application/json

{
"statusCode": 200,
"request_id": "a78010ec-a2bd-41e7-9c0d-654449103c7b",
"timestamp": "2026-08-13T14:05:02.000Z",
"message": "Document checked",
"data": {
  "valid": false,
  "profile": "pint-om-billing-invoice",
  "document_type_code": "380",
  "error_count": 1,
  "warning_count": 1,
  "issues": [
    {
      "severity": "error",
      "code": "IBR-019-OM",
      "message": "Buyer address line 1 (IBT-050), line 2 (IBT-051), line 3 (IBT-163), city (IBT-052) and post code (IBT-053) MUST be present when the transaction type is a Full tax invoice",
      "location": "/Invoice/cac:AccountingCustomerParty/cac:Party/cac:PostalAddress"
    },
    {
      "severity": "warning",
      "code": "ALIGNED-IBRP-S-09-OM-WARN",
      "message": "The VAT category tax amount for category S does not exactly equal the sum of invoice-line VAT amounts",
      "location": "/Invoice/cac:TaxTotal"
    }
  ],
  "sender_id": "0248:OM1100449001",
  "receiver_id": "0248:OM1100449002",
  "document_id": "INV-2026-0001",
  "issue_date": "2026-08-13"
}
}