POST /v1/parse

Parse an e-invoice XML or hybrid PDF into JSON, with a list of what the document holds beyond it.

Upload an invoice or credit note (XML or PDF) and get its main fields back as JSON.

The JSON is a subset of the document. What the document holds beyond it is listed in warnings, in every response.

Both XML documents and hybrid PDFs are supported.

Parse XML:

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:

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)

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

Headers

Query parameters

A query parameter this table does not list answers 400 VALIDATION_ERROR, and error.details.fields names it as a JSON Pointer, such as /formt.

Request body

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

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)

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",
    "profileUrn": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
    "businessProcessId": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
    "invoice": {
      "number": "INV-2026-001",
      "issueDate": "2026-04-13",
      "currencyCode": "EUR",
      "documentType": "invoice",
      "typeCode": "380",
      "buyerReference": "04011000-12345-03",
      "seller": {
        "name": "Acme GmbH",
        "address": {
          "street": "Musterstraße 1",
          "city": "Berlin",
          "postalCode": "10115",
          "countryCode": "DE"
        },
        "vatId": "DE123456789"
      },
      "buyer": {
        "name": "Bundesministerium für Beispiele",
        "address": {
          "street": "Beispielweg 42",
          "city": "Bonn",
          "postalCode": "53113",
          "countryCode": "DE"
        }
      },
      "lines": [
        {
          "description": "IT consulting, April 2026",
          "quantity": 20.0,
          "unitCode": "HUR",
          "unitPrice": 120.0,
          "lineTotal": 2400.0,
          "vatRate": 19.0,
          "vatCategoryCode": "S"
        }
      ],
      "totalNetAmount": 2400.0,
      "totalTaxAmount": 456.0,
      "totalGrossAmount": 2856.0
    },
    "warnings": [
      {
        "code": "PARSE_NOT_RETURNED",
        "message": "The document holds elements that this response does not return. elements lists each one by its path, with the number of times it occurs. terms names these EN 16931 business groups when one is among them: BG-3, BG-16, BG-20, BG-21, BG-23, BG-27, BG-28, BG-32. Attributes of an element that was read are not listed.",
        "elements": [
          {
            "path": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeAgreement/ram:BuyerTradeParty/ram:URIUniversalCommunication",
            "count": 1
          },
          {
            "path": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeAgreement/ram:SellerTradeParty/ram:URIUniversalCommunication",
            "count": 1
          },
          {
            "path": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:ApplicableTradeTax",
            "count": 1
          },
          {
            "path": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradePaymentTerms",
            "count": 1
          },
          {
            "path": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:DuePayableAmount",
            "count": 1
          },
          {
            "path": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementHeaderMonetarySummation/ram:TaxBasisTotalAmount",
            "count": 1
          },
          {
            "path": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeSettlement/ram:SpecifiedTradeSettlementPaymentMeans",
            "count": 1
          },
          {
            "path": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:IncludedSupplyChainTradeLineItem/ram:AssociatedDocumentLineDocument",
            "count": 1
          },
          {
            "path": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:IncludedSupplyChainTradeLineItem/ram:SpecifiedLineTradeSettlement/ram:ApplicableTradeTax/ram:TypeCode",
            "count": 1
          }
        ],
        "terms": [
          "BG-16",
          "BG-23"
        ]
      }
    ]
  }
}

The document behind this example also carries a due date, payment terms, payment means and both parties’ electronic addresses. None of them is in invoice, and each is in warnings.

Parse response object

Parsed invoice object

The parsed invoice uses the field names of the generate request invoice object and returns the fields in the tables below, whether the input was UBL or CII. It returns no other field of that object.

Every field but lines is returned only when the document states a value for it.

Parsed party object

address is left out when the postal address states none of its values.

Parsed invoice line object

A line that states none of these values is an empty object, so a line’s position in lines is its position in the document.

Numbers and dates

A number is returned when the element’s text is a decimal number as XML Schema writes one (xs:decimal): digits, with an optional sign and an optional fraction after a point, such as 1200, -5.50 or .5. Text in any other form, such as 1e3 or 1,200.00, is not read as a number. The response carries the number as a floating-point number. A decimal with more digits than that holds comes back as the nearest number it can hold.

A date is read by the form the document’s syntax prescribes:

• UBL: the text must be an xs:date, a calendar date written YYYY-MM-DD. It is returned as the document writes it, with its time zone when it has one (2026-04-13+02:00). A day the month does not have, such as 2026-02-30, is not a date.
• CII: the udt:DateTimeString must carry format="102" and hold YYYYMMDD, and it is returned as YYYY-MM-DD. Text under another format, or under none, is not read as a date. The day is not held to the month: CEN’s rule for this form, CII-DT-097, admits days 01 to 31 in every month, so 20260230 comes back as 2026-02-30.

Text that is not read as a number or a date leaves the field out, and a PARSE_VALUE_NOT_FOUND warning names the field and the element. So does a decimal too large for a floating-point number.

Warnings

Each entry of warnings has a code and a message, and the fields its code calls for.

PARSE_NOT_RETURNED

Lists every element of the document that holds text or an attribute and that the parser did not read. An element whose text was read and refused as a number or a date is not listed here: it comes under PARSE_VALUE_NOT_FOUND. An element is listed once, at the top of the part that was not read: payment means with five children are one entry. path is written with the usual prefixes (/Invoice/cac:PaymentMeans, /rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/...), and count is how often that path occurs. An element in a namespace outside UBL and CII is written with its namespace in braces. An attribute of an element that was read, such as a schemeID or a currencyID, is not listed.

terms names the business groups below when one is among the listed elements. Other terms are not named: find them by path.

Each group is found the way the rule context of that name selects it in CEN’s EN 16931 validation artefacts, the ones POST /v1/validate runs. An allowance or charge whose indicator is none of the values above is listed by its path and named as neither.

PARSE_VALUE_NOT_FOUND

The document holds something where field is read from, and it is not one value the response can return. field is then left out of invoice. The warning has two shapes:

• With elements and no terms: an element holds text that was not read as a number or a date. elements lists each such element by path, and count is the number of elements at that path whose text was not read. The text itself is not repeated. There is one warning per field and reason, not one per occurrence. For a field of an invoice line, field is written without an index (lines[].unitPrice), so the warning covers every line whose value was not read and does not say which lines they are.
• With terms ["BT-110"] and no elements: the document holds several total VAT amounts in its document currency, and the parser does not choose among them. field is totalTaxAmount. EN 16931 rule BR-CO-15 requires exactly one such amount on UBL, and on CII unless the total with VAT (BT-112) equals the total without VAT (BT-109).

A value the document does not state draws no PARSE_VALUE_NOT_FOUND: an element that is missing, is empty or holds only white space leaves its field out.

Parsed delivery object

The deliver-to party, place and date, read from cac:Delivery on UBL and from ram:ApplicableHeaderTradeDelivery on CII. The field names are those of the generate delivery object. A field is returned only when the document has a value for it.

Parsed delivery address object

One value sent to POST /v1/generate does not come back from a CII document: a locationId.schemeId outside the ISO 6523 ICD list. Generate writes such an identifier to the unqualified ram:ID, because BR-CL-26 rejects a non-ICD scheme on ram:GlobalID, so the document holds no scheme to read. UBL keeps it.

400 PARSE_FAILED example

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

• The parsed JSON uses the field names of the generate endpoint input. It is a subset of the document, so a document generated from it is not the document that was parsed: everything warnings lists is missing from it.
• A field the document states no value for is left out of the response. It is not set to null, 0 or an empty string: see what an absent field means.
• For hybrid PDFs, Beliq reads the embedded XML attachment automatically.