API Reference

POST /v1/parse

POST/v1/parse

Parse an e-invoice XML or hybrid PDF into a normalized JSON representation.

Upload an invoice file (XML or PDF) and get invoice fields back as normalized JSON.

Both XML invoices and hybrid PDFs are supported.

Quick copy examples

Parse XML:

parse-xml.sh

curl -X POST https://api.beliq.eu/v1/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml

import { readFile } from 'node:fs/promises';

import { Beliq } from '@beliq/sdk';

const beliq = new Beliq({ apiKey: process.env.BELIQ_API_KEY! });

const parsed = await beliq.parse(await readFile('invoice.xml'));

console.log(parsed.format, parsed.profileDetected);
console.log(parsed.invoice);

import os
from pathlib import Path

from beliq import Beliq

beliq = Beliq(api_key=os.environ["BELIQ_API_KEY"])

parsed = beliq.parse(Path("invoice.xml").read_bytes())

print(parsed.format, parsed.profile_detected)
print(parsed.invoice)

Parse PDF:

parse-pdf.sh

curl -X POST https://api.beliq.eu/v1/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @invoice.pdf

import { readFile } from 'node:fs/promises';

import { Beliq } from '@beliq/sdk';

const beliq = new Beliq({ apiKey: process.env.BELIQ_API_KEY! });

const parsed = await beliq.parse(await readFile('invoice.pdf'));

console.log(parsed.format, parsed.profileDetected);
console.log(parsed.invoice);

import os
from pathlib import Path

from beliq import Beliq

beliq = Beliq(api_key=os.environ["BELIQ_API_KEY"])

parsed = beliq.parse(Path("invoice.pdf").read_bytes())

print(parsed.format, parsed.profile_detected)
print(parsed.invoice)

Request

POST /v1/parse
Content-Type: application/xml | application/octet-stream
Authorization: Bearer <api-key>

Headers

Header	Required	Description
`Authorization`	required	`Bearer <api-key>` or use `X-API-Key` header
`Content-Type`	required	`application/xml` for XML input, `application/octet-stream` for PDF or binary input

Query parameters

Parameter	Type	Required	Description
`format`	string	optional	Format hint: `auto`, `cii`, or `ubl`. When set to `auto` (default), the engine detects the format automatically

Request body

The raw XML or PDF file content as the request body. Do not JSON-encode it.

parse.sh

curl -X POST https://api.beliq.eu/v1/parse \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @invoice.xml

import { readFile } from 'node:fs/promises';

import { Beliq } from '@beliq/sdk';

const beliq = new Beliq({ apiKey: process.env.BELIQ_API_KEY! });

const parsed = await beliq.parse(await readFile('invoice.xml'));

console.log(parsed.format, parsed.profileDetected);
console.log(parsed.invoice);

import os
from pathlib import Path

from beliq import Beliq

beliq = Beliq(api_key=os.environ["BELIQ_API_KEY"])

parsed = beliq.parse(Path("invoice.xml").read_bytes())

print(parsed.format, parsed.profile_detected)
print(parsed.invoice)

Response

Alongside the JSON body below, the response reports the detected syntax and profile as headers. See the Response headers reference.

Success (200)

{
  "success": true,
  "data": {
    "format": "cii",
    "profileDetected": "XRechnung",
    "invoice": {
      "number": "INV-2026-001",
      "issueDate": "2026-04-13",
      "dueDate": "2026-05-13",
      "currencyCode": "EUR",
      "buyerReference": "04011000-12345-03",
      "seller": {
        "name": "Acme GmbH",
        "vatId": "DE123456789",
        "email": "billing@acme.example",
        "address": {
          "street": "Musterstraße 1",
          "city": "Berlin",
          "postalCode": "10115",
          "countryCode": "DE"
        }
      },
      "buyer": {
        "name": "Bundesministerium für Beispiele",
        "vatId": "DE987654321",
        "email": "rechnung@beispiel.example",
        "address": {
          "street": "Beispielweg 42",
          "city": "Bonn",
          "postalCode": "53113",
          "countryCode": "DE"
        }
      },
      "lines": [
        {
          "description": "IT consulting — April 2026",
          "quantity": 20,
          "unitCode": "HUR",
          "unitPrice": 120.00,
          "lineTotal": 2400.00,
          "vatRate": 19,
          "vatCategoryCode": "S"
        }
      ],
      "paymentMeans": {
        "typeCode": "58",
        "iban": "DE89370400440532013000",
        "bic": "COBADEFFXXX"
      },
      "paymentTerms": "Net 30 days",
      "totalNetAmount": 2400.00,
      "totalTaxAmount": 456.00,
      "totalGrossAmount": 2856.00
    }
  }
}

Parse response object

Field	Type	Description
`format`	string	Detected input format: `cii` or `ubl`
`profileDetected`	string?	Detected CIUS profile, if any
`invoice`	Invoice	Normalized invoice data

Parsed invoice object

The parsed invoice follows the same structure as the generate request invoice object. All fields are extracted from the source XML and normalized to a consistent JSON shape regardless of whether the input was UBL or CII.

Field	Type	Always present	Description
`number`	string	always	Invoice number
`issueDate`	string	always	Issue date (`YYYY-MM-DD`)
`dueDate`	string	optional	Payment due date
`currencyCode`	string	always	ISO 4217 currency code
`buyerReference`	string	optional	Buyer reference
`orderReference`	string	optional	Purchase order reference
`note`	string	optional	Free-text note
`seller`	Party	always	Seller details
`buyer`	Party	always	Buyer details
`lines`	InvoiceLine[]	always	Line items
`taxSummary`	TaxSummary[]	optional	VAT breakdown per category
`paymentMeans`	PaymentMeans	optional	Payment details
`paymentTerms`	string	optional	Payment terms
`totalNetAmount`	number	always	Total excluding VAT
`totalTaxAmount`	number	always	Total VAT
`totalGrossAmount`	number	always	Total including VAT

Error responses

HTTP Status	Error Code	When
400	`VALIDATION_ERROR`	Request body is empty or not a valid file
400	`PARSE_FAILED`	The input could not be parsed as a valid e-invoice (malformed XML, unsupported format, no embedded XML in PDF)
413	`VALIDATION_ERROR`	Request body is larger than this endpoint’s 1 MB size limit. The cap is enforced before the body is read, so nothing was validated and no quota unit is spent
415	`VALIDATION_ERROR`	The `Content-Type` is not one this route accepts (`application/xml`, `text/xml`, `application/octet-stream`, `application/pdf`). The free public demo is narrower: XML only, and PDF bytes are refused even when labelled as XML
503	`ENGINE_UNAVAILABLE`	The validation engine is temporarily unavailable

400 PARSE_FAILED example

{
  "success": false,
  "error": {
    "code": "PARSE_FAILED",
    "message": "Could not parse XML: element 'Invoice' not found in expected namespace"
  }
}

Notes

The parsed JSON uses the same field names as the generate endpoint input, so you can parse, edit, and regenerate invoices.
Optional fields that are not present in the source XML are omitted from the response (not set to null).
For hybrid PDFs, Beliq reads the embedded XML attachment automatically.