Guides
Schema Reference
Every document — invoice, passport, medical report, legal contract, or anything else — returns the exact same JSON structure. Write your integration once and it works for every document type in the world.
One schema. Every document.:The API auto-detects the document type. Your code always reads the same top-level keys. Each block (
vendor, financial, identity, etc.) is omitted entirely when not applicable — null fields are never returned.Universal Response Schema
This is the complete structure. Blocks not relevant to the detected document type are omitted from the response — only populated fields are returned.
response.json
{
// ── Envelope (always present) ─────────────────────────────────
"job_id": "extr_a1b2c3d4e5f6",
"status": "success",
"document_type": "invoice", // auto-detected type
"document_category": "financial", // financial | legal | identity | medical | insurance | tax | logistics | hr | education | property | transport | government | travel | other
"confidence": 0.97, // float 0.0–1.0
// ── Vendor / Issuer ───────────────────────────────────────────
"vendor": {
"name": "string | null",
"address": "string | null",
"phone": "string | null",
"email": "string | null",
"website": "string | null",
"gstin": "string | null",
"pan": "string | null",
"tax_id": "string | null",
"registration_number": "string | null",
"country": "string | null"
},
// ── Buyer / Recipient ─────────────────────────────────────────
"buyer": {
"name": "string | null",
"address": "string | null",
"phone": "string | null",
"email": "string | null",
"website": "string | null",
"gstin": "string | null",
"pan": "string | null",
"tax_id": "string | null",
"registration_number": "string | null",
"country": "string | null",
"table_number": "string | null", // for restaurant receipts
"customer_id": "string | null"
},
// ── Document metadata ─────────────────────────────────────────
"document_meta": {
"document_number": "string | null",
"invoice_number": "string | null",
"date": "string | null", // YYYY-MM-DD
"time": "string | null", // HH:mm:ss
"due_date": "string | null",
"expiry_date": "string | null",
"currency": "string | null", // ISO 4217 e.g. "INR"
"language": "string | null", // ISO 639-1 e.g. "en"
"country": "string | null"
},
// ── Financial data ────────────────────────────────────────────
"financial": {
"line_items": [
{
"description": "string",
"quantity": "number | null",
"unit": "string | null",
"unit_price": "number | null",
"total": "number | null",
"hsn_code": "string | null",
"tax_rate": "number | null",
"discount": "number | null"
}
],
"totals": {
"subtotal": "number | null",
"discount": "number | null",
"tax_total": "number | null",
"cgst": "number | null",
"sgst": "number | null",
"igst": "number | null",
"vat": "number | null",
"service_charge": "number | null",
"grand_total": "number | null",
"amount_due": "number | null"
},
"payment": {
"method": "string | null", // cash | card | upi | bank_transfer | cheque | crypto | other
"amount_paid": "number | null",
"change_returned": "number | null",
"bank_name": "string | null",
"account_number": "string | null",
"ifsc": "string | null",
"upi_id": "string | null",
"transaction_id": "string | null"
}
},
// ── Identity / Travel ─────────────────────────────────────────
"identity": {
"full_name": "string | null",
"date_of_birth": "string | null",
"gender": "string | null",
"nationality": "string | null",
"id_number": "string | null",
"id_type": "string | null",
"issue_date": "string | null",
"expiry_date": "string | null",
"issuing_authority": "string | null",
"address": "string | null",
"mrz": "string | null"
},
// ── Bank statement ────────────────────────────────────────────
"bank_statement": {
"account_holder": "string | null",
"account_number": "string | null",
"bank_name": "string | null",
"ifsc": "string | null",
"swift": "string | null",
"statement_period":"string | null",
"opening_balance": "number | null",
"closing_balance": "number | null",
"transactions": [
{
"date": "string | null",
"description": "string | null",
"debit": "number | null",
"credit": "number | null",
"balance": "number | null",
"reference": "string | null"
}
]
},
// ── Medical ───────────────────────────────────────────────────
"medical": {
"patient_name": "string | null",
"patient_dob": "string | null",
"patient_id": "string | null",
"patient_phone": "string | null",
"patient_email": "string | null",
"patient_address": "string | null",
"doctor_name": "string | null",
"specialization": "string | null",
"visit_date": "string | null",
"ihi_number": "string | null",
"assessment": "string | null",
"diagnosis": "string | null",
"prescription": "string | null",
"lab_results": "string | null",
"follow_up_date": "string | null"
},
// ── Resume / CV ───────────────────────────────────────────────
"resume": {
"full_name": "string | null",
"email": "string | null",
"phone": "string | null",
"address": "string | null",
"linkedin": "string | null",
"github": "string | null",
"website": "string | null",
"summary": "string | null",
"skills": ["string"],
"languages": ["string"],
"work_experience": [
{
"company": "string | null",
"title": "string | null",
"start_date": "string | null",
"end_date": "string | null",
"location": "string | null",
"description": "string | null"
}
],
"education": [
{
"institution": "string | null",
"degree": "string | null",
"field_of_study": "string | null",
"start_date": "string | null",
"end_date": "string | null",
"grade": "string | null"
}
],
"certifications": ["string"]
},
// ── Legal / Contract ──────────────────────────────────────────
"legal": {
"contract_title": "string | null",
"parties": ["string"],
"effective_date": "string | null",
"expiry_date": "string | null",
"governing_law": "string | null",
"jurisdiction": "string | null",
"contract_value": "number | null",
"currency": "string | null",
"payment_terms": "string | null",
"termination_clause": "string | null",
"key_obligations": ["string"]
},
// ── Shipping / Logistics ──────────────────────────────────────
"shipping": {
"tracking_number": "string | null",
"carrier": "string | null",
"service_type": "string | null",
"ship_date": "string | null",
"estimated_delivery": "string | null",
"actual_delivery": "string | null",
"sender_name": "string | null",
"sender_address": "string | null",
"recipient_name": "string | null",
"recipient_address": "string | null",
"weight": "string | null",
"dimensions": "string | null",
"declared_value": "number | null",
"currency": "string | null"
},
// ── Insurance ─────────────────────────────────────────────────
"insurance": {
"policy_number": "string | null",
"policy_type": "string | null",
"insurer": "string | null",
"insured_name": "string | null",
"insured_dob": "string | null",
"coverage_amount": "number | null",
"premium_amount": "number | null",
"currency": "string | null",
"start_date": "string | null",
"end_date": "string | null",
"nominees": ["string"]
},
// ── Payslip / Salary ──────────────────────────────────────────
"payslip": {
"employee_name": "string | null",
"employee_id": "string | null",
"employer_name": "string | null",
"designation": "string | null",
"department": "string | null",
"pay_period": "string | null",
"basic_salary": "number | null",
"allowances": "number | null",
"gross_salary": "number | null",
"deductions": "number | null",
"net_salary": "number | null",
"currency": "string | null",
"bank_account": "string | null",
"pan": "string | null",
"pf_number": "string | null"
},
// ── Education ───────────────────────────────────────────────
"education": {
"certificate_type": "string | null", // degree, marksheet, transcript, diploma, bonafide
"institution": "string | null",
"institution_address":"string | null",
"university": "string | null",
"student_name": "string | null",
"roll_number": "string | null",
"degree": "string | null",
"specialization": "string | null",
"year_of_admission": "number | null",
"year_of_passing": "number | null",
"grade": "string | null", // e.g. "8.4 CGPA", "First Class"
"division": "string | null",
"subjects": [
{
"name": "string | null",
"grade": "string | null",
"credits": "number | null",
"marks_obtained": "number | null",
"marks_total": "number | null"
}
],
"certificate_number": "string | null",
"issue_date": "string | null",
"signatory": "string | null"
},
// ── Property / Real estate ──────────────────────────────────
"property": {
"document_subtype": "string | null", // sale_deed, rental_agreement, khata, encumbrance, property_tax
"registration_number": "string | null",
"registration_date": "string | null",
"sub_registrar_office":"string | null",
"seller_name": "string | null",
"seller_address": "string | null",
"buyer_name": "string | null",
"buyer_address": "string | null",
"property_address": "string | null",
"survey_number": "string | null",
"khata_number": "string | null",
"built_up_area_sqft": "number | null",
"carpet_area_sqft": "number | null",
"property_type": "string | null", // residential, commercial, agricultural, industrial
"sale_consideration": "number | null",
"guidance_value": "number | null",
"stamp_duty_paid": "number | null",
"registration_fee": "number | null",
"currency": "string | null",
"encumbrances": "string | null"
},
// ── Vehicle / Transport ─────────────────────────────────────
"vehicle": {
"document_subtype": "string | null", // registration_certificate, driving_licence, puc, fitness
"registration_number": "string | null",
"owner_name": "string | null",
"owner_address": "string | null",
"chassis_number": "string | null",
"engine_number": "string | null",
"make": "string | null",
"model": "string | null",
"variant": "string | null",
"fuel_type": "string | null",
"color": "string | null",
"body_type": "string | null",
"seating_capacity": "number | null",
"manufacturing_date": "string | null",
"registration_date": "string | null",
"registration_valid_until": "string | null",
"insurance_company": "string | null",
"insurance_valid_until": "string | null",
"rto_office": "string | null",
"hypothecation": "string | null"
},
// ── Tax return ──────────────────────────────────────────────
"tax_return": {
"return_type": "string | null", // itr-1, itr-2, form_26as, gstr-1, gstr-3b, gstr-9
"pan": "string | null",
"gstin": "string | null",
"full_name": "string | null",
"assessment_year": "string | null",
"financial_year": "string | null",
"filing_date": "string | null",
"gross_income": "number | null",
"total_deductions": "number | null",
"taxable_income": "number | null",
"tax_payable": "number | null",
"tds_credited": "number | null",
"advance_tax_paid": "number | null",
"refund_due": "number | null",
"tax_paid": "number | null",
"currency": "string | null"
},
// ── Customs / Import-Export ─────────────────────────────────
"customs": {
"document_subtype": "string | null", // bill_of_entry, shipping_bill, clearance, iec
"bill_number": "string | null",
"date": "string | null",
"importer_exporter_name": "string | null",
"importer_exporter_address": "string | null",
"iec_code": "string | null",
"port_of_entry": "string | null",
"port_of_origin": "string | null",
"vessel_flight": "string | null",
"items": [
{
"description": "string | null",
"quantity": "number | null",
"unit": "string | null",
"value": "number | null",
"duty": "number | null",
"hs_code": "string | null",
"country_of_origin":"string | null"
}
],
"total_value": "number | null",
"total_duty": "number | null",
"currency": "string | null",
"customs_office": "string | null"
},
// ── Ticket / Boarding pass ──────────────────────────────────
"ticket": {
"ticket_type": "string | null", // flight, train, bus, event, movie, concert
"pnr": "string | null",
"ticket_number": "string | null",
"passenger_name": "string | null",
"departure": "string | null",
"arrival": "string | null",
"departure_date": "string | null",
"departure_time": "string | null",
"arrival_date": "string | null",
"arrival_time": "string | null",
"seat": "string | null",
"class_type": "string | null", // economy, business, first, sleeper, 2AC, etc.
"gate": "string | null",
"terminal": "string | null",
"carrier": "string | null", // airline, railway, bus operator
"fare": "number | null",
"currency": "string | null",
"booking_reference": "string | null",
"event_name": "string | null",
"venue": "string | null"
},
// ── Government certificate ──────────────────────────────────
"government_cert": {
"certificate_type": "string | null", // birth, death, marriage, domicile, caste, income, police_clearance
"certificate_number": "string | null",
"full_name": "string | null",
"date_of_birth": "string | null",
"date_of_event": "string | null", // birth date, death date, marriage date
"place_of_event": "string | null",
"father_name": "string | null",
"mother_name": "string | null",
"spouse_name": "string | null",
"gender": "string | null",
"address": "string | null",
"issuing_authority": "string | null",
"registration_number": "string | null",
"registration_date": "string | null",
"registration_district":"string | null",
"issue_date": "string | null",
"valid_until": "string | null",
"purpose": "string | null"
},
// ── Validation ────────────────────────────────────────────────
"validation": {
"gstin_valid": "boolean | null",
"math_valid": "boolean | null",
"warnings": ["string"]
},
// ── Raw data ──────────────────────────────────────────────────
"raw_text": "string | null", // full OCR text of the document
"extraction_notes": "string | null" // model notes about extraction quality
}Top-level Fields
| Parameter | Type | Required | Description |
|---|---|---|---|
job_id | string | Optional | Unique extraction job identifier. Format: "extr_" + 12 hex chars. |
status | string | Optional | "success" when extraction completed. |
document_type | string | Optional | Auto-detected type: invoice, receipt, purchase_order, restaurant_receipt, contract, identity, bank_statement, medical, legal, payslip, resume, insurance, utility_bill, tax_form, tax_return, shipping, education, property, vehicle, customs, ticket, government_cert, other. |
document_category | string | Optional | High-level category: financial, legal, identity, medical, insurance, tax, logistics, hr, education, property, transport, government, travel, other. |
confidence | float | Optional | Model confidence from 0.0 to 1.0. Values above 0.85 are high accuracy. |
vendor | VendorInfo | null | Optional | Issuer / seller / company / provider details. Populated for invoices, receipts, bills, etc. |
buyer | BuyerInfo | null | Optional | Buyer / customer / recipient details. |
document_meta | DocumentMeta | null | Optional | Document number, dates, currency, language, country. |
financial | FinancialData | null | Optional | Line items, totals (subtotal, GST breakdown, grand_total), and payment info. |
identity | IdentityInfo | null | Optional | Name, DOB, ID number, MRZ, issuing authority. For passports, Aadhaar, PAN, DL, etc. |
bank_statement | BankStatementData | null | Optional | Account info, opening/closing balance, and list of transactions. |
medical | MedicalData | null | Optional | Patient and doctor info, diagnosis, prescription, lab results. |
resume | ResumeData | null | Optional | Contact info, skills, work experience, education, certifications. |
legal | LegalData | null | Optional | Contract title, parties, dates, governing law, key obligations. |
shipping | ShippingData | null | Optional | Tracking number, carrier, sender/recipient, weight, dimensions. |
insurance | InsuranceData | null | Optional | Policy number, coverage, premium, dates, nominees. |
payslip | PayslipData | null | Optional | Employee/employer info, salary breakdown, deductions, net salary. |
education | EducationData | null | Optional | Degree certificates, mark sheets, transcripts, diplomas. Institution, degree, subjects, grades. |
property | PropertyData | null | Optional | Sale deeds, rental agreements, Khata, encumbrance certificates. Seller/buyer, address, area, value. |
vehicle | VehicleData | null | Optional | RC books, driving licences, PUC, fitness certificates. Registration, chassis, make/model, validity. |
tax_return | TaxReturnData | null | Optional | ITR, Form 26AS, GSTR-1/3B/9. Income, deductions, tax payable, TDS credited, refund due. |
customs | CustomsData | null | Optional | Bill of entry, shipping bill, customs clearance. IEC code, ports, items with HS codes and duties. |
ticket | TicketData | null | Optional | Flight, train, bus, event tickets and boarding passes. PNR, seat, departure/arrival, carrier, fare. |
government_cert | GovernmentCertData | null | Optional | Birth, death, marriage, domicile, caste, income certificates. Personal details, issuing authority, dates. |
validation | ValidationInfo | null | Optional | GSTIN checksum and math reconciliation results, plus any warnings. |
raw_text | string | null | Optional | Full OCR text extracted from the document. Useful for debugging or custom parsing. |
extraction_notes | string | null | Optional | Model notes about extraction quality, ambiguities, or low-confidence areas. |
How to use in your app
Because the schema is uniform, you can write a single handler for all document types. Just check which blocks are non-null:
handler.py
import requests
def process_document(file_path: str) -> dict:
res = requests.post(
"https://api.documentflowai.com/v1/extract",
headers={"Authorization": "Bearer af_YOUR_API_KEY"},
files={"file": open(file_path, "rb")},
)
data = res.json()
# Universal — works for ANY document type
print(f"Job : {data['job_id']}")
print(f"Type : {data['document_type']} ({data['document_category']})")
print(f"Confidence : {data['confidence']}")
# Access vendor info (invoices, receipts, bills)
if data.get("vendor"):
print(f"Vendor : {data['vendor']['name']}")
# Access financial data (invoices, receipts, POs)
if data.get("financial"):
fin = data["financial"]
for item in fin.get("line_items", []):
print(f" - {item['description']}: {item['total']}")
if fin.get("totals"):
print(f"Grand Total: {fin['totals']['grand_total']} {data['document_meta']['currency']}")
# Access identity (passport, Aadhaar, PAN)
if data.get("identity"):
print(f"Name : {data['identity']['full_name']}")
print(f"ID : {data['identity']['id_number']}")
# Access bank statement
if data.get("bank_statement"):
bs = data["bank_statement"]
print(f"Account : {bs['account_number']} at {bs['bank_name']}")
for txn in bs.get("transactions", []):
print(f" {txn['date']}: {txn['description']} | {txn['debit'] or txn['credit']}")
# Validation results
if data.get("validation"):
v = data["validation"]
if v.get("gstin_valid") is not None:
print(f"GSTIN valid: {v['gstin_valid']}")
if v.get("math_valid") is not None:
print(f"Math valid : {v['math_valid']}")
for w in v.get("warnings", []):
print(f" ⚠ {w}")
return datahandler.ts
const res = await fetch(
"https://api.documentflowai.com/v1/extract",
{
method: "POST",
headers: { Authorization: `Bearer ${API_KEY}` },
body: form,
}
);
const data = await res.json();
// Universal — same code path for any document
console.log(data.job_id, data.document_type, data.confidence);
// Financial documents
if (data.financial) {
data.financial.line_items.forEach(item =>
console.log(item.description, item.total)
);
console.log("Total:", data.financial.totals?.grand_total);
}
// Identity documents
if (data.identity) {
console.log(data.identity.full_name, data.identity.id_number);
}
// Bank statements
if (data.bank_statement) {
data.bank_statement.transactions.forEach(txn =>
console.log(txn.date, txn.description, txn.debit ?? txn.credit)
);
}Check for key presence, not null:Blocks are omitted entirely when not relevant — they won't be present in the response at all. Use
data.get("block") in Python or data.block?. in TypeScript to safely access them.