Invoice JSON Extraction API Reference
Read a structured XML invoice and return it as an InvoiceDocument JSON. The endpoint accepts either a PDF (whose embedded CII / UBL XML attachment is used) or a standalone XML file. Pure XML parsing, no AI. Use /v1/parse/json if your PDF has no embedded XML and you need the data extracted with AI.
One of three extraction routes: the invoice extraction overview shows which endpoint fits which document.
https://api.invoicexml.com/v1/extract/json
Code Example
curl -X POST https://api.invoicexml.com/v1/extract/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.
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": "H87",
"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": "H87"
},
"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": "H87",
"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": "H87"
},
"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"
}
]
}}
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.
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.