📄 JSON Schema & Output Format
Detailed specification of the JSON structure returned by ExtractBill's document parsing API.
Overview
Every successfully parsed document returns a standardized JSON structure containing extracted data from your documents. This format is consistent across all document types (invoices, receipts, bills, purchase orders, etc.) to ensure predictable integration.
Standardized structure across all document types
Same JSON format for invoices, receipts, bills, and more
Confidence scores for data quality
Each extraction includes a confidence score (0-1)
Nullable fields for flexibility
Fields may be null if not found in the document
Document Structure
The parsed data structure contains three main sections:
1. Document Metadata
Basic information about the document type and classification
{
"document": {
"type": "invoice",
"language": "en",
"currency": "USD"
}
}2. Parties
Information about supplier (seller) and customer (buyer)
{
"supplier": { ... },
"customer": { ... }
}3. Financial Data
Line items, amounts, taxes, and payment details
{
"invoice_number": "INV-2024-001",
"date": "2024-11-07",
"due_date": "2024-12-07",
"line_items": [ ... ],
"amounts": { ... },
"payment": { ... }
}Field Reference
Complete reference of all fields in the parsed JSON output.
| Field | Type | Description |
|---|---|---|
| document.type | string | Document type: invoice, receipt, bill, purchase_order, etc. |
| document.language | string | Document language (ISO 639-1 code): en, de, fr, etc. |
| document.currency | string | Currency code (ISO 4217): USD, EUR, GBP, etc. |
| invoice_number | string|null | Invoice/receipt number or identifier |
| date | string|null | Document date (ISO 8601: YYYY-MM-DD) |
| due_date | string|null | Payment due date (ISO 8601: YYYY-MM-DD) |
| supplier | object|null | Supplier/vendor information (see Supplier Object) |
| customer | object|null | Customer/buyer information (see Customer Object) |
| line_items | array | List of items/services (see Line Item Object) |
| amounts | object | Financial totals (subtotal, tax, total) |
| payment | object|null | Payment details (method, terms, bank info) |
| notes | string|null | Additional notes or comments on the document |
Nested Objects
Supplier / Customer Object
| name | string|null | Company or person name |
| address | string|null | Full address (street, city, postal code, country) |
| tax_id | string|null | Tax ID / VAT number |
| string|null | Email address | |
| phone | string|null | Phone number |
Line Item Object
| description | string | Item description |
| quantity | number|null | Quantity ordered/delivered |
| unit_price | number|null | Price per unit |
| total | number|null | Total line amount (quantity × unit_price) |
| tax_rate | number|null | Tax rate as decimal (e.g., 0.19 for 19%) |
Amounts Object
| subtotal | number|null | Subtotal before tax |
| tax | number|null | Total tax amount |
| total | number | Grand total (subtotal + tax) |
| discount | number|null | Discount amount applied |
Payment Object
| method | string|null | Payment method (e.g., "bank_transfer", "credit_card") |
| terms | string|null | Payment terms (e.g., "Net 30", "Due on receipt") |
| bank_account | string|null | Bank account number / IBAN |
Examples
Real-world examples of parsed JSON output for different document types.
{
"document": {
"type": "invoice",
"language": "en",
"currency": "USD"
},
"invoice_number": "INV-2024-001",
"date": "2024-11-07",
"due_date": "2024-12-07",
"supplier": {
"name": "Acme Corporation",
"address": "123 Business St, San Francisco, CA 94105, USA",
"tax_id": "12-3456789",
"email": "billing@acme.com",
"phone": "+1 415-555-0100"
},
"customer": {
"name": "Example Company LLC",
"address": "456 Market St, New York, NY 10001, USA",
"tax_id": "98-7654321",
"email": "accounts@example.com",
"phone": "+1 212-555-0200"
},
"line_items": [
{
"description": "Professional Services - Q4 2024",
"quantity": 40,
"unit_price": 150.00,
"total": 6000.00,
"tax_rate": 0.10
},
{
"description": "Cloud Infrastructure - November",
"quantity": 1,
"unit_price": 500.00,
"total": 500.00,
"tax_rate": 0.10
}
],
"amounts": {
"subtotal": 6500.00,
"tax": 650.00,
"total": 7150.00,
"discount": null
},
"payment": {
"method": "bank_transfer",
"terms": "Net 30",
"bank_account": "US12 3456 7890 1234 5678 90"
},
"notes": "Payment due within 30 days. Thank you for your business!"
}{
"document": {
"type": "receipt",
"language": "en",
"currency": "USD"
},
"invoice_number": "RCP-20241107-0042",
"date": "2024-11-07",
"due_date": null,
"supplier": {
"name": "Coffee Shop Downtown",
"address": "789 Main St, Portland, OR 97201, USA",
"tax_id": null,
"email": null,
"phone": "+1 503-555-0300"
},
"customer": null,
"line_items": [
{
"description": "Cappuccino - Large",
"quantity": 2,
"unit_price": 4.50,
"total": 9.00,
"tax_rate": 0.08
},
{
"description": "Croissant",
"quantity": 1,
"unit_price": 3.50,
"total": 3.50,
"tax_rate": 0.08
}
],
"amounts": {
"subtotal": 12.50,
"tax": 1.00,
"total": 13.50,
"discount": null
},
"payment": {
"method": "credit_card",
"terms": null,
"bank_account": null
},
"notes": null
}{
"document": {
"type": "bill",
"language": "en",
"currency": "USD"
},
"invoice_number": "ELEC-20241107",
"date": "2024-11-07",
"due_date": "2024-11-28",
"supplier": {
"name": "City Power & Light",
"address": "100 Energy Plaza, Austin, TX 78701, USA",
"tax_id": "45-6789012",
"email": "billing@citypower.com",
"phone": "+1 512-555-0400"
},
"customer": {
"name": "John Doe",
"address": "321 Oak Avenue, Austin, TX 78704, USA",
"tax_id": null,
"email": "john.doe@email.com",
"phone": "+1 512-555-0500"
},
"line_items": [
{
"description": "Electricity Usage - October 2024 (850 kWh)",
"quantity": 850,
"unit_price": 0.12,
"total": 102.00,
"tax_rate": 0.00
},
{
"description": "Service Charge",
"quantity": 1,
"unit_price": 15.00,
"total": 15.00,
"tax_rate": 0.00
}
],
"amounts": {
"subtotal": 117.00,
"tax": 0.00,
"total": 117.00,
"discount": null
},
"payment": {
"method": "bank_transfer",
"terms": "Due by 2024-11-28",
"bank_account": "Account: 1234567890"
},
"notes": "Account Number: 123456789. Thank you for being a valued customer."
}Webhook Payload
When a document completes processing, ExtractBill sends a webhook to your configured endpoint. The webhook payload includes the complete parsed data plus metadata.
{
"event": "document.completed",
"document": {
"id": "d-a3k9f2x8m1p",
"status": "completed",
"confidence_score": 0.98,
"parsed_data": {
"document": {
"type": "invoice",
"language": "en",
"currency": "USD"
},
"invoice_number": "INV-2024-001",
"date": "2024-11-07",
"supplier": { ... },
"customer": { ... },
"line_items": [ ... ],
"amounts": { ... },
"payment": { ... },
"notes": null
},
"created_at": "2024-11-07T10:30:00Z",
"completed_at": "2024-11-07T10:30:03Z"
},
"delivered_at": "2024-11-07T10:30:04Z"
}Webhook Events
document.completed- Sent when document parsing succeedsdocument.failed- Sent when document parsing fails
For full webhook documentation, see Webhooks Guide.
JSON Schema
Formal JSON Schema (Draft 7) for validation and code generation. You can use this schema with validation libraries in your language of choice.
Download JSON Schema
Direct link: https://www.extractbill.com/schemas/parsed-document-schema.json
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "ExtractBill Parsed Document",
"type": "object",
"required": ["document", "amounts"],
"properties": {
"document": {
"type": "object",
"required": ["type", "language", "currency"],
"properties": {
"type": {
"type": "string",
"enum": ["invoice", "receipt", "bill", "purchase_order", "credit_note", "unknown"]
},
"language": {
"type": "string",
"pattern": "^[a-z]{2}$"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
}
}
},
"invoice_number": {
"type": ["string", "null"]
},
"date": {
"type": ["string", "null"],
"format": "date"
},
"due_date": {
"type": ["string", "null"],
"format": "date"
},
"supplier": {
"type": ["object", "null"],
"properties": {
"name": { "type": ["string", "null"] },
"address": { "type": ["string", "null"] },
"tax_id": { "type": ["string", "null"] },
"email": { "type": ["string", "null"], "format": "email" },
"phone": { "type": ["string", "null"] }
}
},
"customer": {
"type": ["object", "null"],
"properties": {
"name": { "type": ["string", "null"] },
"address": { "type": ["string", "null"] },
"tax_id": { "type": ["string", "null"] },
"email": { "type": ["string", "null"], "format": "email" },
"phone": { "type": ["string", "null"] }
}
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"required": ["description"],
"properties": {
"description": { "type": "string" },
"quantity": { "type": ["number", "null"] },
"unit_price": { "type": ["number", "null"] },
"total": { "type": ["number", "null"] },
"tax_rate": { "type": ["number", "null"], "minimum": 0, "maximum": 1 }
}
}
},
"amounts": {
"type": "object",
"required": ["total"],
"properties": {
"subtotal": { "type": ["number", "null"] },
"tax": { "type": ["number", "null"] },
"total": { "type": "number" },
"discount": { "type": ["number", "null"] }
}
},
"payment": {
"type": ["object", "null"],
"properties": {
"method": { "type": ["string", "null"] },
"terms": { "type": ["string", "null"] },
"bank_account": { "type": ["string", "null"] }
}
},
"notes": {
"type": ["string", "null"]
}
}
}Using the Schema
You can validate parsed JSON responses against this schema using standard JSON Schema validators:
Python:
jsonschema