AI Invoice Parsing API Reference
Parse any invoice PDF into a structured InvoiceDocument JSON using AI. The endpoint accepts native PDFs, scanned documents, and image-based PDFs, then runs OCR, semantic field extraction, and EN 16931 mapping. Any embedded XML in the PDF is ignored. Use /v1/extract/json if you want the embedded XML parsed instead.
https://api.invoicexml.com/v1/parse/json
Code Example
curl -X POST https://api.invoicexml.com/v1/parse/json \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "[email protected]"
Try it out online, no coding required
Upload any invoice and download the structured JSON instantly, right in your browser.
Request
| Parameter | Type | Description |
|---|---|---|
| file * | binary | The invoice file to process. |
Content-Type: multipart/form-data
The source and target formats are part of the endpoint path, and everything else (syntax, declared profile, specification identifier) is read from the document itself, so there is nothing more to configure.
Headers
| Header | Value |
|---|---|
| Authorization * | Bearer YOUR_API_KEY |
| Content-Type | multipart/form-data |
Response
200 Extracted JSON
Returns the parsed invoice data as a structured JSON object.
The response filename is derived from the uploaded file: {original-name}.json.
The Content-Disposition header is set to attachment for direct download.
The root object carries the full extracted document under an invoice key,
so your client reads response.invoice.seller,
response.invoice.totals, response.invoice.lines
and so on. Fields that are not present on the source document are returned as
null. The envelope mirrors the request body of the
/v1/create endpoints, so a response can be piped straight
back into invoice creation.
Confidence scores
As a sibling of the invoice object, the response carries a
confidence object with the AI's self-rated extraction confidence:
an overall score plus four areas,
each ranging from 0.0 (the AI had to guess) to
1.0 (the document was unambiguous).
// 200 OK { "invoice": { "invoiceNumber": "RE-2026-0142", "issueDate": "2026-07-01", "seller": { ... }, "buyer": { ... }, "totals": { ... }, "lines": [ ... ] }, "confidence": { "overall": 0.91, "areas": { "sellerIdentification": 0.95, "buyerIdentification": 0.90, "taxCalculation": 0.98, "lineItems": 0.82 } } }
sellerIdentification: seller name, address, VAT and legal registration identifiers.buyerIdentification: buyer name, address, and identifiers.taxCalculation: VAT breakdowns, rates, and document totals arithmetic.lineItems: line rows, quantities, unit prices, and line amounts.
overall is the average of the reported area scores, rounded to two decimals.
Treat 0.9 and above as a clean read; anything below
0.7 means the layout was confusing or the AI had to guess, and the
affected area deserves human review before the data enters your books. An area score is
null when the pipeline reported none for that area, and the whole
confidence property is omitted in the rare case that no scores were
reported at all. Deterministic /v1/extract/json responses never
include it, so response.invoice reads identically across both endpoints.
Complete example response
The example below shows every field of the InvoiceDocument model
populated, so you can see the exact shape your parser has to handle: header terms, seller and buyer
groups, delivery, payment details, totals, VAT breakdowns, line items with price details and item
attributes, document level allowances and charges, supporting documents, and preceding invoice
references. A real response contains the same properties for every invoice; whatever the source
document does not carry is returned as null (or as an empty array
for repeating groups), never omitted.
Show the complete example response (all fields populated)
{
"invoice": {
"invoiceNumber": "INV-2026-0042",
"issueDate": "2026-06-14",
"dueDate": "2026-07-14",
"typeCode": "380",
"currency": "EUR",
"taxCurrency": null,
"specificationId": "urn:cen.eu:en16931:2017",
"businessProcessType": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0",
"buyerReference": "BUYER-REF-2026-998",
"purchaseOrderReference": "PO-2026-5571",
"notes": [
"Thank you for your business.",
"Goods delivered to the Lyon warehouse during May 2026."
],
"vatPointDateCode": "3",
"supportingDocuments": [
{
"reference": "TIMESHEET-2026-05",
"schemeId": null,
"documentTypeCode": "916",
"description": "Signed timesheet for May 2026",
"externalUri": "https://docs.example.com/timesheets/2026-05.pdf",
"attachment": "JVBERi0xLjcK",
"attachmentMimeCode": "application/pdf",
"attachmentFilename": "timesheet-2026-05.pdf"
}
],
"precedingInvoiceReferences": [
{ "reference": "INV-2026-0031", "issueDate": "2026-05-02" }
],
"seller": {
"name": "Muster Lieferant GmbH",
"tradingName": "Muster Supplies",
"postalAddress": {
"line1": "Lieferantenstrasse 20",
"line2": "Gebaeude 4",
"line3": "Etage 3",
"city": "Berlin",
"postCode": "10115",
"countrySubdivision": "Berlin",
"country": "DE"
},
"contact": {
"name": "Max Mustermann",
"phone": "+49 30 1234567",
"email": "[email protected]"
},
"identifiers": [
{ "identifier": "4000001000005", "schemeId": "0088" }
],
"legalRegistration": { "identifier": "HRB 12345", "schemeId": "0002" },
"vatIdentifier": "DE123456789",
"taxRegistrationIdentifier": "201/123/12345",
"additionalLegalInformation": "Geschaeftsfuehrer: Max Mustermann. Amtsgericht Berlin HRB 12345.",
"electronicAddress": { "identifier": "DE123456789", "schemeId": "9930" }
},
"buyer": {
"name": "Client Acheteur SARL",
"tradingName": "Acheteur Retail",
"postalAddress": {
"line1": "12 Rue de l'Acheteur",
"line2": "Batiment B",
"line3": "Bureau 210",
"city": "Lyon",
"postCode": "69002",
"countrySubdivision": "Auvergne-Rhone-Alpes",
"country": "FR"
},
"contact": {
"name": "Marie Durand",
"phone": "+33 4 78 00 00 00",
"email": "[email protected]"
},
"identifiers": [
{ "identifier": "3000002000003", "schemeId": "0088" }
],
"legalRegistration": { "identifier": "303 265 045", "schemeId": "0002" },
"vatIdentifier": "FR40303265045",
"electronicAddress": { "identifier": "FR40303265045", "schemeId": "9957" }
},
"delivery": {
"receiverName": "Acheteur Warehouse Lyon",
"locationIdentifier": "3000002000010",
"actualDeliveryDate": "2026-05-30",
"deliveryAddress": {
"line1": "5 Avenue de la Logistique",
"line2": "Quai 7",
"line3": "Zone C",
"city": "Venissieux",
"postCode": "69200",
"countrySubdivision": "Auvergne-Rhone-Alpes",
"country": "FR"
}
},
"invoicingPeriod": {
"startDate": "2026-05-01",
"endDate": "2026-05-31"
},
"paymentDetails": {
"paymentMeansCode": "58",
"paymentMeansText": "SEPA credit transfer to the main account",
"remittanceInformation": "INV-2026-0042",
"paymentAccountIdentifier": "DE89370400440532013000",
"paymentAccountName": "Muster Lieferant GmbH",
"bic": "COBADEFFXXX",
"mandateReference": "MNDT-2026-0042",
"paymentTerms": "Payment within 30 days net. 2% discount if paid within 10 days."
},
"totals": {
"sumOfLineNetAmounts": 975.00,
"sumOfAllowances": 15.00,
"sumOfCharges": 30.00,
"taxBasisTotalAmount": 990.00,
"taxTotalAmount": 176.10,
"taxTotalAmountInAccountingCurrency": null,
"grandTotalAmount": 1166.10,
"paidAmount": 100.00,
"roundingAmount": 0.00,
"duePayableAmount": 1066.10
},
"vatBreakdowns": [
{
"taxableAmount": 890.00,
"taxAmount": 169.10,
"categoryCode": "S",
"rate": 19,
"exemptionReasonText": null,
"exemptionReasonCode": null
},
{
"taxableAmount": 100.00,
"taxAmount": 7.00,
"categoryCode": "S",
"rate": 7,
"exemptionReasonText": null,
"exemptionReasonCode": null
}
],
"lines": [
{
"lineId": "1",
"lineNote": "Includes 12-month standard warranty.",
"objectIdentifier": { "identifier": "OBJ-AB-001", "schemeId": "AAJ" },
"quantity": 10,
"unitCode": "C62",
"lineNetAmount": 875.00,
"buyerOrderLineReference": "PO-2026-5571-1",
"lineBuyerAccountingReference": "COSTCENTER-4711",
"linePeriod": { "startDate": "2026-05-01", "endDate": "2026-05-31" },
"priceDetails": {
"netPrice": 90.00,
"discountAmount": 10.00,
"grossPrice": 100.00,
"priceBaseQuantity": 1,
"priceBaseUnit": "C62"
},
"vatInformation": { "categoryCode": "S", "rate": 19 },
"item": {
"name": "Ergonomic office chair",
"description": "Adjustable ergonomic office chair, black mesh back.",
"sellerIdentifier": "CHAIR-ERGO-BLK",
"buyerIdentifier": "BUY-CHR-001",
"standardIdentifier": { "identifier": "4012345000009", "schemeId": "0160" },
"classifications": [
{ "identifier": "56101700", "schemeId": "STI", "schemeVersion": "26.0801" }
],
"attributes": [
{ "name": "Colour", "value": "Black" },
{ "name": "Backrest", "value": "Mesh" }
],
"countryOfOrigin": "DE"
},
"allowances": [
{
"amount": 50.00,
"baseAmount": 1000.00,
"percentage": 5,
"reason": "Volume discount",
"reasonCode": "95"
}
],
"charges": [
{
"amount": 25.00,
"baseAmount": 1000.00,
"percentage": 2.5,
"reason": "Handling and packaging",
"reasonCode": "FC"
}
]
},
{
"lineId": "2",
"lineNote": "Reduced-rate consumable.",
"objectIdentifier": { "identifier": "OBJ-AB-002", "schemeId": "AAJ" },
"quantity": 5,
"unitCode": "C62",
"lineNetAmount": 100.00,
"buyerOrderLineReference": "PO-2026-5571-2",
"lineBuyerAccountingReference": "COSTCENTER-4712",
"linePeriod": { "startDate": "2026-05-01", "endDate": "2026-05-31" },
"priceDetails": {
"netPrice": 20.00,
"discountAmount": 5.00,
"grossPrice": 25.00,
"priceBaseQuantity": 1,
"priceBaseUnit": "C62"
},
"vatInformation": { "categoryCode": "S", "rate": 7 },
"item": {
"name": "Printed product catalogue",
"description": "Full-colour A4 product catalogue, 120 pages.",
"sellerIdentifier": "CAT-2026",
"buyerIdentifier": "BUY-CAT-002",
"standardIdentifier": { "identifier": "4012345000160", "schemeId": "0160" },
"classifications": [
{ "identifier": "55101500", "schemeId": "STI", "schemeVersion": "26.0801" }
],
"attributes": [],
"countryOfOrigin": "DE"
},
"allowances": [],
"charges": []
}
],
"allowances": [
{
"amount": 15.00,
"baseAmount": 300.00,
"percentage": 5,
"vatCategoryCode": "S",
"vatRate": 19,
"reason": "Loyalty rebate",
"reasonCode": "100"
}
],
"charges": [
{
"amount": 30.00,
"baseAmount": 600.00,
"percentage": 5,
"vatCategoryCode": "S",
"vatRate": 19,
"reason": "Freight",
"reasonCode": "FC"
}
]
},
"confidence": {
"overall": 0.91,
"areas": {
"sellerIdentification": 0.95,
"buyerIdentification": 0.90,
"taxCalculation": 0.98,
"lineItems": 0.92
}
}}
How the Parse Invoice JSON API Works
The API runs a four-stage pipeline on every uploaded document to guarantee a validated, integration-ready JSON object:
Document ingestion & OCR
The uploaded file is decoded and, if necessary, passed through an OCR engine. Native PDFs are parsed at the text layer; scanned PDFs, JPEG, PNG, TIFF, and WEBP files are processed via optical character recognition before any field extraction begins.
AI field extraction & semantic mapping
A large-language model reads the full document and identifies every invoice field, seller, buyer, invoice number, date, line items, tax rates, payment terms, bank details, regardless of layout, language, or formatting. Fields are mapped to a normalised schema, and the model self-rates its confidence for each extraction area. The scores are returned in the confidence block of the response.
Multi-layer validation & cross-referencing
Four validation passes run sequentially:
- Schema: all mandatory EN 16931 fields present, correct data types, valid code-list values.
- Tax numbers: VAT IDs and business registration numbers verified against country-specific format rules.
- Addresses: seller and buyer addresses parsed into components and checked for internal consistency.
- Arithmetic: unit price × quantity = line total; sum of line totals + tax amounts = invoice grand total.
Discrepancies are corrected deterministically where the arithmetic allows it and otherwise surface as lower confidence scores rather than blocking the API response, so your application can decide how to handle borderline cases.
Structured JSON delivery
The validated invoice object is serialised as application/json and returned with Content-Disposition: attachment. Field names are consistent across all source documents, languages, and invoice formats, no post-processing required before API integration.
Frequently Asked Questions
Does this work with scanned or photographed invoices?
Yes, that is the primary use case. The AI reads the document like a human, recognising fields regardless of layout, orientation, scan quality, or language. It handles thermal-printed receipts, faxed documents, and smartphone photos of paper invoices.
How does this differ from /v1/extract/json?
/v1/extract/json deterministically parses embedded or uploaded XML. /v1/parse/json runs the AI pipeline on the PDF itself and ignores any embedded XML. Use parse when the PDF has no XML or when you want a fresh AI read regardless of what is embedded.
What does the JSON output contain?
An envelope with the BT-first InvoiceDocument under an invoice key (invoiceNumber, issueDate, currency, seller, buyer, paymentDetails, lines, totals, vatBreakdowns, and the rest of the EN 16931 model) plus a confidence sibling with the AI's overall and per-area scores. The envelope matches /v1/extract/json and mirrors the /v1/create request body, so you can swap endpoints or pipe a response straight into invoice creation.
What do the confidence scores mean?
Every response carries a confidence object alongside the invoice: an overall score plus four area scores (sellerIdentification, buyerIdentification, taxCalculation, lineItems), each from 0.0 to 1.0. Overall is the average of the reported area scores. Treat 0.9 and above as an unambiguous read; anything below 0.7 means the AI had to guess and that area deserves human review. Clients that do not care about it can simply ignore it and read invoice directly.
What file formats are accepted?
PDF only (native and scanned). Maximum file size is 20 MB.
What happens if the document is not an invoice?
The AI classification step returns a 400 with errorCode 4008 (NotAnInvoice). If the PDF contains multiple invoices, errorCode 4009 (MultipleInvoices) is returned.