Billhorse API

Set your API key

You received it by e-mail during the private beta.

export BILLHORSE_API_KEY="bh_live_…"

Validate a sample invoice

Use our example file (valid XRechnung 3.0) or your own XML/PDF:

# Download the sample, then validate it
curl -sO https://billhorse.com/docs/examples/xrechnung-valid.xml
curl -s -X POST https://api.billhorse.com/v1/validate \
  -H "Authorization: Bearer $BILLHORSE_API_KEY" \
  --data-binary @xrechnung-valid.xml

Response (abridged):

{
  "valid": true,
  "profile": { "label": "XRechnung 3.0", "en16931": true, "xrechnung": true },
  "meta": { "number": "RE-2026-0815", "grandTotal": "178.50", … },
  "findings": [],
  "counts": { "error": 0, "warning": 0, "info": 0 }
}

See what errors look like

The broken sample triggers eight findings. Every finding carries a rule id — each one has a human explanation page:

{
  "valid": false,
  "findings": [
    { "id": "BR-DE-15", "severity": "error",
      "message": "XRechnung: buyer reference (BT-10, …) is mandatory." },
    { "id": "BR-CO-16", "severity": "error",
      "expected": "178.50", "actual": "170.00", … }
  ]
}

→ billhorse.com/en/rules/br-de-15 explains the rule and the fix, in EN, DE and FR. Messages come in English by default — add ?lang=de or ?lang=fr to show them to your end users in their language.

Parse into normalized JSON

/v1/parse extracts the EN 16931 semantic model — the same JSON shape whether the input was UBL, CII or a hybrid PDF:

curl -s -X POST https://api.billhorse.com/v1/parse \
  -H "Authorization: Bearer $BILLHORSE_API_KEY" \
  --data-binary @rechnung.pdf

{
  "invoice": {
    "number": "RE-2026-0815", "docType": "invoice", "currency": "EUR",
    "seller": { "name": "…", "vatId": "DE123456789", "country": "DE" },
    "totals": { "netTotal": "150", "taxTotal": "28.5", "due": "178.5" },
    "lines": [ … ], "vat": [ … ]
  },
  "report": { "valid": true, … }
}