Reference / JSON Schema
JSON Schema Reference
The /v1/serialize endpoint returns a versioned, typed JSON object designed for direct ERP consumption. This page documents every field.
Schema Versioning
Every response includes a schema_version field following semantic versioning:
- Patch (1.0.x) — Bug fixes, no field changes
- Minor (1.x.0) — New optional fields added. Existing fields unchanged.
- Major (x.0.0) — Breaking changes. Field renames, removals, or type changes.
Response Envelope
| Field | Type | Required | Description |
|---|---|---|---|
| success | boolean | Yes | Whether serialization completed without errors |
| schema_version | string | No | Semantic version of the invoice schema (default: "1.0.0") |
| engine_version | string | No | Engine version that produced this response (e.g., "1.x.x") |
| invoice | BusinessReadyInvoice | null | No | The extracted invoice data. Null on failure. |
| errors | object[] | No | Array of error objects (empty on success) |
BusinessReadyInvoice
The core invoice object. All monetary amounts accept both number and string types for precision safety.
| Field | Type | Required | Description |
|---|---|---|---|
| invoice_number | string | Yes | Invoice identifier (BT-1) |
| invoice_date | string (date) | Yes | Issue date in YYYY-MM-DD format (BT-2) |
| due_date | string (date) | null | No | Payment due date in YYYY-MM-DD format (BT-9) |
| currency | string | No | ISO 4217 currency code (default: "EUR") (BT-5) |
| buyer_reference | string | null | No | Buyer reference / PO number (BT-10) |
| contract_reference | string | null | No | Contract reference (BT-12) |
| seller | PartySchema | Yes | Seller / supplier details |
| buyer | PartySchema | Yes | Buyer / customer details |
| line_items | LineItemSchema[] | Yes | Invoice line items |
| tax_breakdown | TaxBreakdownSchema[] | Yes | Tax subtotals per category/rate |
| total_net_amount | number | string | Yes | Sum of line totals before tax (BT-106) |
| total_tax_amount | number | string | Yes | Total tax amount (BT-110) |
| total_gross_amount | number | string | Yes | Total with tax (BT-112) |
| amount_due | number | string | Yes | Amount due for payment (BT-115) |
| format | string | Yes | Detected format: "factur-x", "zugferd", "xrechnung", "ubl" |
| profile | string | Yes | Detected profile: "minimum", "basic", "en16931", "extended" |
PartySchema
Normalized seller/buyer representation. Only name is required.
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Legal company name |
| vat_number | string | null | No | VAT ID with country prefix (e.g., "FR12345678901") |
| registration_id | string | null | No | Trade registration number (SIRET, HRB, etc.) |
| address | AddressSchema | null | No | Physical address |
| string | null | No | Contact email address |
AddressSchema
| Field | Type | Required | Description |
|---|---|---|---|
| line1 | string | Yes | Street address line 1 |
| line2 | string | null | No | Street address line 2 |
| city | string | Yes | City name |
| postcode | string | Yes | Postal code |
| country_code | string | Yes | ISO 3166-1 alpha-2 country code (e.g., "FR", "DE") |
LineItemSchema
High-precision invoice line item. Monetary values and quantities accept both number and string types.
| Field | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Item name (BT-153) |
| description | string | null | No | Item description (BT-154) |
| quantity | number | string | Yes | Invoiced quantity (BT-129) |
| unit_code | string | Yes | UN/ECE Rec 20 unit code (e.g., "C62", "HUR") |
| unit_label | string | null | No | Human-readable unit (e.g., "piece", "hour") |
| net_price | number | string | Yes | Net unit price (BT-146) |
| line_total | number | string | Yes | Net line total = Qty × Price (BT-131) |
| vat_rate | number | string | Yes | VAT percentage (e.g., 20.00) |
| vat_category | string | No | VAT category code (default: "S" = Standard) |
TaxBreakdownSchema
| Field | Type | Required | Description |
|---|---|---|---|
| category | string | Yes | VAT category code ("S", "Z", "E", "AE", etc.) |
| rate | number | string | Yes | VAT rate percentage |
| basis_amount | number | string | Yes | Taxable base amount for this category |
| tax_amount | number | string | Yes | Calculated tax amount for this category |
Field Mapping Between Endpoints
Field names differ between extraction, serialization, and conversion endpoints. Use this mapping when passing data between endpoints:
| Business Term | /v1/extract | /v1/serialize | /v1/convert |
|---|---|---|---|
| Invoice Date | invoice_date | invoice_date | issue_date |
| Country Code | country | country_code | country_code |
| Buyer / Seller | Nested objects | Nested objects | Nested objects |
Important: To regenerate a validated file from an extracted one, you must map invoice_date to issue_date and country to country_code.
Example Response
/v1/serialize response
JSON
{
"success": true,
"schema_version": "1.0.0",
"engine_version": "1.x.x",
"invoice": {
"invoice_number": "INV-2025-0042",
"invoice_date": "2025-03-01",
"due_date": "2025-03-31",
"currency": "EUR",
"seller": {
"name": "ACME SAS",
"vat_number": "FR12345678901"
},
"buyer": {
"name": "Client Corp",
"buyer_reference": "PO-9981"
},
"line_items": [{
"name": "Consulting services",
"quantity": 5,
"unit_code": "HUR",
"net_price": 150.00,
"line_total": 750.00,
"vat_rate": 20.0
}],
"tax_breakdown": [{
"category": "S",
"rate": 20.0,
"basis_amount": 750.00,
"tax_amount": 150.00
}],
"total_net_amount": 750.00,
"total_tax_amount": 150.00,
"total_gross_amount": 900.00,
"amount_due": 900.00,
"format": "factur-x",
"profile": "en16931"
}
}See Also
Try /v1/serialize
The serialize endpoint is a Pro feature. Start a 30-day evaluation.