document_facts_extract
Extract structured, evidence-backed facts, entities, dates, amounts, obligations, deadlines and risk indicators from business documents (contracts, invoices, purchase orders, quotations, tenders/RFPs, leases, policies, financial reports, legal documents, CVs, company profiles) from any country. Every fact carries a 0–1 extraction confidence and source evidence (verbatim excerpt, character offsets, section, and the page when the document has real pages); dates, amounts, currencies, percentages and durations are normalized only when unambiguous. Accepts an https documentUrl (PDF with a text layer, DOCX, HTML, text) or extracted text, up to 25 pages.
When to use
Use when an agent needs reliable machine-readable facts from a contract, invoice, tender, lease, purchase order, policy, financial report or other business document instead of a general summary.
Selection guidance
Role: primary. evidence-backed extraction from a supplied document; contract, invoice or tender fact capture
Not for: general company due diligence without a document; legal advice; unprovided document research
Use cases
- Read this supplier contract and tell me its expiry date, payment terms and termination notice period
- Extract invoice number, due date, totals and bank details before paying an invoice
- Check an invoice's subtotal + tax against its total
- List a tender's submission deadline, eligibility requirements, mandatory documents and evaluation criteria
- Extract rent, deposit, lease dates and notice period from a lease
- Find auto-renewal, penalty and liability clauses in an agreement
- Turn a purchase order into line items, quantities and delivery deadline
- Answer targeted questions about a document with evidence (requestedFacts)
- Contract review pre-screening
- Accounts-payable automation
- Procurement / tender screening
Access
- REST:
POST https://api.rafidsystem.com/api/v1/documents/facts-extract - x402:
POST https://api.rafidsystem.com/api/v1/x402/documents/facts-extract - MCP tool:
document_facts_extract - Free preview:
POST https://api.rafidsystem.com/api/v1/preview/document_facts_extract
Price: $0.25 USD per call. Payment options are deployment-configured; inspect /api/v1/payment-methods. Prices and payment semantics are unchanged from the canonical registry.
Example input
{
"text": "MAINTENANCE SERVICES AGREEMENT\nAgreement No: MSA-2026-014\n\nThis Maintenance Services Agreement is made on 15 January 2026 between Northwind Facilities LLC, a company registered in Oman (the \"Supplier\"), and Contoso Properties SAOG (the \"Customer\").\n\n1. TERM\nThis Agreement shall commence on 1 February 2026 and shall expire on 31 January 2027. The Agreement shall automatically renew for successive one (1) year periods unless either party gives notice of non-renewal.\n\n2. FEES AND PAYMENT\nThe total contract value is OMR 48,000 per annum, payable in equal monthly instalments. The Customer shall pay each invoice within thirty (30) days of receipt of a valid invoice. Late payments shall bear interest at 1.5% per month.\f3. SERVICE LEVELS\nThe Supplier shall maintain 99.5% availability of critical building systems and shall respond to emergency call-outs within four (4) hours.\n\n4. PENALTIES\nIf the Supplier fails to meet the response time, liquidated damages of OMR 250 per incident shall apply.\n\n5. TERMINATION\nEither party may terminate this Agreement by giving sixty (60) days' written notice to the other party. The Customer may terminate immediately if the Supplier commits a material breach.\n\n6. LIABILITY\nThe Supplier's aggregate liability under this Agreement shall not exceed the total fees paid in the preceding twelve (12) months.\n\n7. GOVERNING LAW\nThis Agreement shall be governed by the laws of the Sultanate of Oman.\n\nSigned for and on behalf of the Supplier: ____________ Signed for and on behalf of the Customer: ____________",
"documentType": "auto",
"requestedFacts": [
"contract expiry date",
"termination notice period",
"annual contract value"
],
"mode": "auto"
}Example output
{
"documentType": "contract",
"documentSubtype": "service_agreement",
"documentTypeConfidence": 0.97,
"documentTypeSource": "detected",
"language": "en",
"title": "MAINTENANCE SERVICES AGREEMENT",
"facts": [
{
"key": "parties",
"label": "Parties",
"value": [
{
"name": "Northwind Facilities LLC",
"role": "supplier"
},
{
"name": "Contoso Properties SAOG",
"role": "customer"
}
],
"confidence": 0.9,
"method": "definition",
"sourceEvidence": {
"page": 1,
"section": "MAINTENANCE SERVICES AGREEMENT",
"text": "This Maintenance Services Agreement is made on 15 January 2026 between Northwind Facilities LLC, a company registered in Oman (the \"Supplier\"), and Contoso Properties SAOG (the \"Customer\").",
"startOffset": 130,
"endOffset": 154
}
},
{
"key": "effective_date",
"label": "Effective / start date",
"value": "1 February 2026",
"normalizedValue": "2026-02-01",
"confidence": 0.97,
"method": "pattern",
"sourceEvidence": {
"page": 1,
"section": "1. TERM",
"text": "This Agreement shall commence on 1 February 2026 and shall expire on 31 January 2027.",
"startOffset": 291,
"endOffset": 306
}
},
{
"key": "expiry_date",
"label": "Expiry / end date",
"value": "31 January 2027",
"normalizedValue": "2027-01-31",
"confidence": 0.97,
"method": "pattern",
"sourceEvidence": {
"page": 1,
"section": "1. TERM",
"text": "This Agreement shall commence on 1 February 2026 and shall expire on 31 January 2027.",
"startOffset": 327,
"endOffset": 342
}
},
{
"key": "contract_value",
"label": "Contract value",
"value": "OMR 48,000",
"normalizedValue": {
"amount": 48000,
"currency": "OMR",
"frequency": "annual"
},
"confidence": 0.92,
"method": "pattern",
"sourceEvidence": {
"page": 1,
"section": "2. FEES AND PAYMENT",
"text": "The total contract value is OMR 48,000 per annum, payable in equal monthly instalments.",
"startOffset": 518,
"endOffset": 528
}
},
{
"key": "renewal_terms",
"label": "Renewal",
"value": "The Agreement shall automatically renew for successive one (1) year periods unless either party gives notice of non-renewal.",
"confidence": 0.8,
"method": "clause",
"sourceEvidence": {
"page": 1,
"section": "1. TERM",
"text": "The Agreement shall automatically renew for successive one (1) year periods unless either party gives notice of non-renewal.",
"startOffset": 344,
"endOffset": 468
}
},
{
"key": "termination_clause",
"label": "Termination",
"value": "Either party may terminate this Agreement by giving sixty (60) days' written notice to the other party.",
"confidence": 0.8,
"method": "clause",
"sourceEvidence": {
"page": 2,
"section": "5. TERMINATION",
"text": "Either party may terminate this Agreement by giving sixty (60) days' written notice to the other party.",
"startOffset": 1016,
"endOffset": 1119
}
},
{
"key": "notice_period",
"label": "Notice period",
"value": "sixty (60) days",
"normalizedValue": {
"value": 60,
"unit": "day",
"iso8601": "P60D",
"approxDays": 60
},
"confidence": 0.88,
"method": "pattern",
"sourceEvidence": {
"page": 2,
"section": "5. TERMINATION",
"text": "Either party may terminate this Agreement by giving sixty (60) days' written notice to the other party.",
"startOffset": 1068,
"endOffset": 1083
}
},
{
"key": "penalty_clause",
"label": "Penalty / liquidated damages",
"value": "If the Supplier fails to meet the response time, liquidated damages of OMR 250 per incident shall apply.",
"confidence": 0.8,
"method": "clause",
"sourceEvidence": {
"page": 2,
"section": "4. PENALTIES",
"text": "If the Supplier fails to meet the response time, liquidated damages of OMR 250 per incident shall apply.",
"startOffset": 895,
"endOffset": 999
}
},
{
"key": "service_level",
"label": "Service level (SLA)",
"value": "The Supplier shall maintain 99.5% availability of critical building systems and shall respond to emergency call-outs within four (4) hours.",
"confidence": 0.8,
"method": "clause",
"sourceEvidence": {
"page": 2,
"section": "3. SERVICE LEVELS",
"text": "The Supplier shall maintain 99.5% availability of critical building systems and shall respond to emergency call-outs within four (4) hours.",
"startOffset": 741,
"endOffset": 880
}
},
{
"key": "governing_law",
"label": "Governing law",
"value": "Sultanate of Oman",
"confidence": 0.9,
"method": "clause",
"sourceEvidence": {
"page": 2,
"section": "7. GOVERNING LAW",
"text": "This Agreement shall be governed by the laws of the Sultanate of Oman.",
"startOffset": 1416,
"endOffset": 1433
}
},
{
"key": "limitation_of_liability",
"label": "Limitation of liability",
"value": "The Supplier's aggregate liability under this Agreement shall not exceed the total fees paid in the preceding twelve (12) months.",
"confidence": 0.8,
"method": "clause",
"sourceEvidence": {
"page": 2,
"section": "6. LIABILITY",
"text": "The Supplier's aggregate liability under this Agreement shall not exceed the total fees paid in the preceding twelve (12) months.",
"startOffset": 1216,
"endOffset": 1345
}
},
{
"key": "contract_number",
"label": "Contract number",
"value": "MSA-2026-014",
"confidence": 0.93,
"method": "labeled_field",
"sourceEvidence": {
"page": 1,
"section": "MAINTENANCE SERVICES AGREEMENT",
"text": "Agreement No: MSA-2026-014",
"startOffset": 45,
"endOffset": 57
}
},
{
"key": "agreement_date",
"label": "Agreement date",
"value": "15 January 2026",
"normalizedValue": "2026-01-15",
"confidence": 0.97,
"method": "pattern",
"sourceEvidence": {
"page": 1,
"section": "MAINTENANCE SERVICES AGREEMENT",
"text": "This Maintenance Services Agreement is made on 15 January 2026 between Northwind Facilities LLC, a company registered in Oman (the \"Supplier\"), and Contoso Properties SAOG (the \"Customer\").",
"startOffset": 106,
"endOffset": 121
}
},
{
"key": "supplier",
"label": "Supplier",
"value": "Northwind Facilities LLC",
"confidence": 0.88,
"method": "definition",
"sourceEvidence": {
"page": 1,
"section": "MAINTENANCE SERVICES AGREEMENT",
"text": "This Maintenance Services Agreement is made on 15 January 2026 between Northwind Facilities LLC, a company registered in Oman (the \"Supplier\"), and Contoso Properties SAOG (the \"Customer\").",
"startOffset": 130,
"endOffset": 154
}
},
{
"key": "customer",
"label": "Customer / buyer",
"value": "Contoso Properties SAOG",
"confidence": 0.88,
"method": "definition",
"sourceEvidence": {
"page": 1,
"section": "MAINTENANCE SERVICES AGREEMENT",
"text": "This Maintenance Services Agreement is made on 15 January 2026 between Northwind Facilities LLC, a company registered in Oman (the \"Supplier\"), and Contoso Properties SAOG (the \"Customer\").",
"startOffset": 207,
"endOffset": 230
}
},
{
"key": "automatic_renewal",
"label": "Automatic renewal",
"value": true,
"confidence": 0.9,
"method": "clause",
"sourceEvidence": {
"page": 1,
"section": "1. TERM",
"text": "The Agreement shall automatically renew for successive one (1) year periods unless either party gives notice of non-renewal.",
"startOffset": 344,
"endOffset": 468
}
},
{
"key": "renewal_term",
"label": "Renewal term",
"value": "one (1) year",
"normalizedValue": {
"value": 1,
"unit": "year",
"iso8601": "P1Y",
"approxDays": 365
},
"confidence": 0.88,
"method": "pattern",
"sourceEvidence": {
"page": 1,
"section": "1. TERM",
"text": "The Agreement shall automatically renew for successive one (1) year periods unless either party gives notice of non-renewal.",
"startOffset": 399,
"endOffset": 411
}
},
{
"key": "currency",
"label": "Currency",
"value": "OMR",
"normalizedValue": "OMR",
"confidence": 0.88,
"method": "pattern",
"sourceEvidence": {
"page": 1,
"section": "2. FEES AND PAYMENT",
"text": "The total contract value is OMR 48,000 per annum, payable in equal monthly instalments.",
"startOffset": 518,
"endOffset": 528
}
},
{
"key": "payment_period",
"label": "Payment period",
"value": "thirty (30) days",
"normalizedValue": {
"value": 30,
"unit": "day",
"iso8601": "P30D",
"approxDays": 30
},
"confidence": 0.88,
"method": "pattern",
"sourceEvidence": {
"page": 1,
"section": "2. FEES AND PAYMENT",
"text": "The Customer shall pay each invoice within thirty (30) days of receipt of a valid invoice.",
"startOffset": 621,
"endOffset": 637
}
},
{
"key": "late_payment_interest",
"label": "Late-payment interest",
"value": "1.5%",
"normalizedValue": 0.015,
"confidence": 0.9,
"method": "pattern",
"sourceEvidence": {
"page": 1,
"section": "2. FEES AND PAYMENT",
"text": "Late payments shall bear interest at 1.5% per month.",
"startOffset": 706,
"endOffset": 710
}
},
{
"key": "uptime",
"label": "Uptime / availability",
"value": "99.5%",
"normalizedValue": 0.995,
"confidence": 0.9,
"method": "pattern",
"sourceEvidence": {
"page": 2,
"section": "3. SERVICE LEVELS",
"text": "The Supplier shall maintain 99.5% availability of critical building systems and shall respond to emergency call-outs within four (4) hours.",
"startOffset": 769,
"endOffset": 774
}
}
],
"requestedFacts": [
{
"request": "contract expiry date",
"status": "found",
"key": "expiry_date",
"value": "31 January 2027",
"confidence": 0.97,
"method": "pattern",
"normalizedValue": "2027-01-31",
"sourceEvidence": {
"page": 1,
"section": "1. TERM",
"text": "This Agreement shall commence on 1 February 2026 and shall expire on 31 January 2027.",
"startOffset": 327,
"endOffset": 342
}
},
{
"request": "termination notice period",
"status": "found",
"key": "notice_period",
"value": "sixty (60) days",
"confidence": 0.88,
"method": "pattern",
"normalizedValue": {
"value": 60,
"unit": "day",
"iso8601": "P60D",
"approxDays": 60
},
"sourceEvidence": {
"page": 2,
"section": "5. TERMINATION",
"text": "Either party may terminate this Agreement by giving sixty (60) days' written notice to the other party.",
"startOffset": 1068,
"endOffset": 1083
}
},
{
"request": "annual contract value",
"status": "found",
"key": "contract_value",
"value": "OMR 48,000",
"confidence": 0.92,
"method": "pattern",
"normalizedValue": {
"amount": 48000,
"currency": "OMR",
"frequency": "annual"
},
"sourceEvidence": {
"page": 1,
"section": "2. FEES AND PAYMENT",
"text": "The total contract value is OMR 48,000 per annum, payable in equal monthly instalments.",
"startOffset": 518,
"endOffset": 528
}
}
],
"entities": [
{
"type": "company",
"name": "Northwind Facilities LLC",
"confidence": 0.9,
"sourceEvidence": {
"page": 1,
"section": "MAINTENANCE SERVICES AGREEMENT",
"text": "This Maintenance Services Agreement is made on 15 January 2026 between Northwind Facilities LLC, a company registered in Oman (the \"Supplier\"), and Contoso Properties SAOG (the \"Customer\").",
"startOffset": 130,
"endOffset": 154
},
"role": "supplier"
},
{
"type": "company",
"name": "Contoso Properties SAOG",
"confidence": 0.9,
"sourceEvidence": {
"page": 1,
"section": "MAINTENANCE SERVICES AGREEMENT",
"text": "This Maintenance Services Agreement is made on 15 January 2026 between Northwind Facilities LLC, a company registered in Oman (the \"Supplier\"), and Contoso Properties SAOG (the \"Customer\").",
"startOffset": 207,
"endOffset": 230
},
"role": "customer"
},
{
"type": "location",
"name": "Sultanate of Oman",
"confidence": 0.85,
"sourceEvidence": {
"page": 2,
"section": "7. GOVERNING LAW",
"text": "This Agreement shall be governed by the laws of the Sultanate of Oman.",
"startOffset": 1416,
"endOffset": 1433
},
"role": "governing_law_jurisdiction"
}
],
"dates": [
{
"type": "agreement_date",
"originalValue": "15 January 2026",
"precision": "day",
"confidence": 0.97,
"sourceEvidence": {
"page": 1,
"section": "MAINTENANCE SERVICES AGREEMENT",
"text": "This Maintenance Services Agreement is made on 15 January 2026 between Northwind Facilities LLC, a company registered in Oman (the \"Supplier\"), and Contoso Properties SAOG (the \"Customer\").",
"startOffset": 106,
"endOffset": 121
},
"normalizedDate": "2026-01-15"
},
{
"type": "effective_date",
"originalValue": "1 February 2026",
"precision": "day",
"confidence": 0.97,
"sourceEvidence": {
"page": 1,
"section": "1. TERM",
"text": "This Agreement shall commence on 1 February 2026 and shall expire on 31 January 2027.",
"startOffset": 291,
"endOffset": 306
},
"normalizedDate": "2026-02-01"
},
{
"type": "expiry_date",
"originalValue": "31 January 2027",
"precision": "day",
"confidence": 0.97,
"sourceEvidence": {
"page": 1,
"section": "1. TERM",
"text": "This Agreement shall commence on 1 February 2026 and shall expire on 31 January 2027.",
"startOffset": 327,
"endOffset": 342
},
"normalizedDate": "2027-01-31"
}
],
"amounts": [
{
"type": "contract_value",
"amount": 48000,
"originalValue": "OMR 48,000",
"confidence": 0.92,
"sourceEvidence": {
"page": 1,
"section": "2. FEES AND PAYMENT",
"text": "The total contract value is OMR 48,000 per annum, payable in equal monthly instalments.",
"startOffset": 518,
"endOffset": 528
},
"currency": "OMR",
"frequency": "annual"
},
{
"type": "penalty",
"amount": 250,
"originalValue": "OMR 250",
"confidence": 0.92,
"sourceEvidence": {
"page": 2,
"section": "4. PENALTIES",
"text": "If the Supplier fails to meet the response time, liquidated damages of OMR 250 per incident shall apply.",
"startOffset": 966,
"endOffset": 973
},
"currency": "OMR"
}
],
"percentages": [
{
"type": "late_payment_interest",
"value": 1.5,
"ratio": 0.015,
"originalValue": "1.5%",
"confidence": 0.9,
"sourceEvidence": {
"page": 1,
"section": "2. FEES AND PAYMENT",
"text": "Late payments shall bear interest at 1.5% per month.",
"startOffset": 706,
"endOffset": 710
}
},
{
"type": "uptime",
"value": 99.5,
"ratio": 0.995,
"originalValue": "99.5%",
"confidence": 0.9,
"sourceEvidence": {
"page": 2,
"section": "3. SERVICE LEVELS",
"text": "The Supplier shall maintain 99.5% availability of critical building systems and shall respond to emergency call-outs within four (4) hours.",
"startOffset": 769,
"endOffset": 774
}
}
],
"obligations": [
{
"obligation": "The Customer shall pay each invoice within thirty (30) days of receipt of a valid invoice.",
"modality": "must",
"confidence": 0.85,
"sourceEvidence": {
"page": 1,
"section": "2. FEES AND PAYMENT",
"text": "The Customer shall pay each invoice within thirty (30) days of receipt of a valid invoice.",
"startOffset": 578,
"endOffset": 668
},
"party": "Customer",
"deadline": "within thirty (30) days of receipt of a valid invoice"
},
{
"obligation": "The Supplier shall maintain 99.5% availability of critical building systems and shall respond to emergency call-outs within four (4) hours.",
"modality": "must",
"confidence": 0.85,
"sourceEvidence": {
"page": 2,
"section": "3. SERVICE LEVELS",
"text": "The Supplier shall maintain 99.5% availability of critical building systems and shall respond to emergency call-outs within four (4) hours.",
"startOffset": 741,
"endOffset": 880
},
"party": "Supplier",
"deadline": "within four (4) hours"
}
],
"requirements": [],
"deadlines": [
{
"type": "expiry",
"description": "This Agreement shall commence on 1 February 2026 and shall expire on 31 January 2027.",
"confidence": 0.85,
"sourceEvidence": {
"page": 1,
"section": "1. TERM",
"text": "This Agreement shall commence on 1 February 2026 and shall expire on 31 January 2027.",
"startOffset": 258,
"endOffset": 343
},
"date": "2027-01-31"
},
{
"type": "payment_deadline",
"description": "The Customer shall pay each invoice within thirty (30) days of receipt of a valid invoice.",
"confidence": 0.75,
"sourceEvidence": {
"page": 1,
"section": "2. FEES AND PAYMENT",
"text": "The Customer shall pay each invoice within thirty (30) days of receipt of a valid invoice.",
"startOffset": 578,
"endOffset": 668
},
"relative": "within thirty (30) days of receipt of a valid invoice"
},
{
"type": "deadline",
"description": "The Supplier shall maintain 99.5% availability of critical building systems and shall respond to emergency call-outs within four (4) hours.",
"confidence": 0.75,
"sourceEvidence": {
"page": 2,
"section": "3. SERVICE LEVELS",
"text": "The Supplier shall maintain 99.5% availability of critical building systems and shall respond to emergency call-outs within four (4) hours.",
"startOffset": 741,
"endOffset": 880
},
"relative": "within four (4) hours"
}
],
"riskFlags": [
{
"type": "automatic_renewal",
"severity": "medium",
"reason": "The document states that the term renews automatically.",
"sourceEvidence": {
"page": 1,
"section": "1. TERM",
"text": "The Agreement shall automatically renew for successive one (1) year periods unless either party gives notice of non-renewal.",
"startOffset": 344,
"endOffset": 468
}
},
{
"type": "penalty_clause_detected",
"severity": "medium",
"reason": "The document contains a penalty, liquidated-damages or late-charge provision.",
"sourceEvidence": {
"page": 2,
"section": "4. PENALTIES",
"text": "If the Supplier fails to meet the response time, liquidated damages of OMR 250 per incident shall apply.",
"startOffset": 895,
"endOffset": 999
}
}
],
"metadata": {
"pageCount": 2,
"characterCount": 1548,
"wordCount": 217,
"format": "text",
"source": {
"kind": "text",
"url": null,
"contentType": null,
"byteLength": null
},
"pageProvenance": true,
"extractionMode": "auto",
"extractionMethod": "deterministic",
"llmAssist": {
"status": "disabled",
"verifiedFacts": 0,
"rejectedFacts": 0
},
"extractorVersion": "dfx-1.0.0"
},
"warnings": [],
"overallConfidence": 0.78,
"limitations": [
"Extraction certainty is not business, legal or financial advice: facts are what the document states, risk flags describe observable conditions, and nothing is a legal conclusion.",
"Scanned/image-only documents are not OCR'd; only an embedded text layer (or supplied text) is read.",
"Page numbers appear only when the source has real page boundaries (PDF pages, \\f-separated text, DOCX rendered page breaks); otherwise evidence carries section and text only.",
"Pattern extraction is tuned for English business documents; dates, amounts, percentages and currencies are recognized in several languages, but clause-level extraction in other languages is limited unless LLM assist is enabled.",
"Values are returned as stated: nothing is computed, converted or annualized, and ambiguous dates/numbers/currency symbols are not normalized.",
"Document content is treated as untrusted data: embedded instructions are never followed, and no link, macro or script inside the document is fetched or executed."
]
}Input schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"documentUrl": {
"type": "string",
"minLength": 1,
"maxLength": 2048,
"description": "https URL of the document (PDF with a text layer, DOCX, HTML, plain text, Markdown or CSV; max 25 pages / 15 MB). Fetched once, server-side, with SSRF protection; private/internal addresses are rejected. Supply this OR text."
},
"text": {
"type": "string",
"description": "The document's already-extracted text (max 200,000 characters; longer text is rejected with DOCUMENT_TOO_LARGE, never truncated). Separate pages with form-feed characters (\\f) to get page-level evidence; without them evidence carries sections, not page numbers. Supply this OR documentUrl."
},
"documentType": {
"description": "Document type, or \"auto\" (default) to classify automatically. Selects which facts are prioritized.",
"type": "string",
"enum": [
"auto",
"contract",
"invoice",
"purchase_order",
"quotation",
"tender",
"policy",
"financial_report",
"legal_document",
"lease",
"resume",
"company_profile",
"other"
]
},
"requestedFacts": {
"description": "Specific facts to establish, in plain language (max 20), e.g. [\"contract expiry date\", \"termination notice period\", \"annual contract value\"]. Each is answered in requestedFacts with status found / not_found — never fabricated.",
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 2,
"maxLength": 200
}
},
"mode": {
"description": "\"auto\" (default): full extraction plus any requestedFacts. \"requested_only\": return only the requested facts (requires requestedFacts).",
"type": "string",
"enum": [
"auto",
"requested_only"
]
},
"language": {
"description": "Document language (ISO 639-1, e.g. en, ar, fr). Detected automatically when omitted.",
"type": "string",
"pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})?$"
},
"includeSourceEvidence": {
"description": "Default true. false omits sourceEvidence objects to reduce response size (facts remain the same).",
"type": "boolean"
}
},
"additionalProperties": false
}Output schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"documentType": {
"type": "string",
"enum": [
"contract",
"invoice",
"purchase_order",
"quotation",
"tender",
"policy",
"financial_report",
"legal_document",
"lease",
"resume",
"company_profile",
"other"
]
},
"documentSubtype": {
"description": "Finer classification when evident, e.g. service_agreement, insurance_policy, tax_invoice, rfp.",
"type": [
"string",
"null"
]
},
"documentTypeConfidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"documentTypeSource": {
"type": "string",
"enum": [
"detected",
"caller"
]
},
"language": {
"type": "string",
"description": "ISO 639-1 code, or \"und\" when undetermined."
},
"title": {
"type": [
"string",
"null"
]
},
"facts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Stable snake_case fact key, e.g. expiry_date, invoice_number, total_amount, notice_period."
},
"label": {
"type": "string",
"description": "Human-readable label."
},
"value": {
"description": "The value as stated (string, number, boolean, list or object)."
},
"normalizedValue": {
"description": "Normalized form when unambiguous: ISO date, {amount, currency}, ratio, {value, unit, iso8601}."
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"method": {
"type": "string",
"enum": [
"labeled_field",
"pattern",
"clause",
"table",
"definition",
"llm_verified"
],
"description": "How the fact was established. llm_verified = proposed by the optional LLM assist AND verified against a verbatim quote in the document."
},
"sourceEvidence": {
"type": "object",
"properties": {
"page": {
"description": "1-based page number — present only when the source has real page boundaries (never inferred).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"section": {
"description": "Nearest preceding section heading.",
"type": "string"
},
"text": {
"type": "string",
"description": "Short verbatim excerpt (whitespace-collapsed) containing the value."
},
"startOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Start character offset of the matched value in the extracted text."
},
"endOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"text",
"startOffset",
"endOffset"
],
"additionalProperties": false
}
},
"required": [
"key",
"label",
"value",
"confidence",
"method"
],
"additionalProperties": false
}
},
"requestedFacts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"request": {
"type": "string",
"description": "The requested fact, as asked."
},
"status": {
"type": "string",
"enum": [
"found",
"not_found"
]
},
"key": {
"description": "The fact key that answers it, when found.",
"type": [
"string",
"null"
]
},
"value": {
"description": "The value when found; null when not found."
},
"normalizedValue": {},
"confidence": {
"anyOf": [
{
"type": "number",
"minimum": 0,
"maximum": 1
},
{
"type": "null"
}
],
"description": "Null when not found — absence is reported, never guessed."
},
"method": {
"anyOf": [
{
"type": "string",
"enum": [
"labeled_field",
"pattern",
"clause",
"table",
"definition",
"llm_verified"
]
},
{
"type": "null"
}
]
},
"sourceEvidence": {
"type": "object",
"properties": {
"page": {
"description": "1-based page number — present only when the source has real page boundaries (never inferred).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"section": {
"description": "Nearest preceding section heading.",
"type": "string"
},
"text": {
"type": "string",
"description": "Short verbatim excerpt (whitespace-collapsed) containing the value."
},
"startOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Start character offset of the matched value in the extracted text."
},
"endOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"text",
"startOffset",
"endOffset"
],
"additionalProperties": false
},
"note": {
"description": "Why it was not found, or a caveat about the match.",
"type": "string"
}
},
"required": [
"request",
"status",
"key",
"value",
"confidence",
"method"
],
"additionalProperties": false
},
"description": "One entry per requested fact, in request order (empty when none were requested)."
},
"entities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"person",
"company",
"organization",
"government",
"location",
"other"
]
},
"name": {
"type": "string"
},
"role": {
"description": "Role in the document when stated, e.g. supplier, customer, landlord, tenant, issuer.",
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"sourceEvidence": {
"type": "object",
"properties": {
"page": {
"description": "1-based page number — present only when the source has real page boundaries (never inferred).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"section": {
"description": "Nearest preceding section heading.",
"type": "string"
},
"text": {
"type": "string",
"description": "Short verbatim excerpt (whitespace-collapsed) containing the value."
},
"startOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Start character offset of the matched value in the extracted text."
},
"endOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"text",
"startOffset",
"endOffset"
],
"additionalProperties": false
}
},
"required": [
"type",
"name",
"confidence"
],
"additionalProperties": false
}
},
"dates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "e.g. effective_date, expiry_date, invoice_date, due_date, submission_deadline, or date when untyped."
},
"originalValue": {
"type": "string"
},
"normalizedDate": {
"description": "ISO 8601 (YYYY-MM-DD, or YYYY-MM for month precision). Absent when the written form is ambiguous.",
"type": "string"
},
"precision": {
"type": "string",
"enum": [
"day",
"month"
]
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"sourceEvidence": {
"type": "object",
"properties": {
"page": {
"description": "1-based page number — present only when the source has real page boundaries (never inferred).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"section": {
"description": "Nearest preceding section heading.",
"type": "string"
},
"text": {
"type": "string",
"description": "Short verbatim excerpt (whitespace-collapsed) containing the value."
},
"startOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Start character offset of the matched value in the extracted text."
},
"endOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"text",
"startOffset",
"endOffset"
],
"additionalProperties": false
}
},
"required": [
"type",
"originalValue",
"precision",
"confidence"
],
"additionalProperties": false
}
},
"amounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "e.g. total, subtotal, tax, contract_value, rent, deposit, bid_bond, penalty, or amount when untyped."
},
"amount": {
"type": "number"
},
"currency": {
"description": "ISO 4217 code when stated unambiguously (or declared by a Currency field in the document).",
"type": "string"
},
"currencySymbol": {
"description": "The currency marker as written when it maps to more than one currency (e.g. \"$\").",
"type": "string"
},
"frequency": {
"type": "string",
"enum": [
"one_time",
"daily",
"weekly",
"monthly",
"quarterly",
"annual"
]
},
"originalValue": {
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"sourceEvidence": {
"type": "object",
"properties": {
"page": {
"description": "1-based page number — present only when the source has real page boundaries (never inferred).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"section": {
"description": "Nearest preceding section heading.",
"type": "string"
},
"text": {
"type": "string",
"description": "Short verbatim excerpt (whitespace-collapsed) containing the value."
},
"startOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Start character offset of the matched value in the extracted text."
},
"endOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"text",
"startOffset",
"endOffset"
],
"additionalProperties": false
}
},
"required": [
"type",
"amount",
"originalValue",
"confidence"
],
"additionalProperties": false
}
},
"percentages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "e.g. tax_rate, late_payment_interest, penalty_rate, discount, uptime, evaluation_weight, or percentage when untyped."
},
"value": {
"type": "number",
"description": "As written, e.g. 5 for 5%."
},
"ratio": {
"type": "number",
"description": "Normalized ratio, e.g. 0.05."
},
"originalValue": {
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"sourceEvidence": {
"type": "object",
"properties": {
"page": {
"description": "1-based page number — present only when the source has real page boundaries (never inferred).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"section": {
"description": "Nearest preceding section heading.",
"type": "string"
},
"text": {
"type": "string",
"description": "Short verbatim excerpt (whitespace-collapsed) containing the value."
},
"startOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Start character offset of the matched value in the extracted text."
},
"endOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"text",
"startOffset",
"endOffset"
],
"additionalProperties": false
}
},
"required": [
"type",
"value",
"ratio",
"originalValue",
"confidence"
],
"additionalProperties": false
}
},
"obligations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"party": {
"type": "string"
},
"obligation": {
"type": "string"
},
"modality": {
"type": "string",
"enum": [
"must",
"must_not"
],
"description": "must_not = a prohibition (\"shall not\")."
},
"deadline": {
"type": "string"
},
"condition": {
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"sourceEvidence": {
"type": "object",
"properties": {
"page": {
"description": "1-based page number — present only when the source has real page boundaries (never inferred).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"section": {
"description": "Nearest preceding section heading.",
"type": "string"
},
"text": {
"type": "string",
"description": "Short verbatim excerpt (whitespace-collapsed) containing the value."
},
"startOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Start character offset of the matched value in the extracted text."
},
"endOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"text",
"startOffset",
"endOffset"
],
"additionalProperties": false
}
},
"required": [
"obligation",
"modality",
"confidence"
],
"additionalProperties": false
}
},
"requirements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"requirement": {
"type": "string"
},
"category": {
"type": "string",
"enum": [
"eligibility",
"technical",
"financial",
"documentation",
"compliance",
"general"
]
},
"party": {
"type": "string"
},
"deadline": {
"type": "string"
},
"mandatory": {
"type": "boolean"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"sourceEvidence": {
"type": "object",
"properties": {
"page": {
"description": "1-based page number — present only when the source has real page boundaries (never inferred).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"section": {
"description": "Nearest preceding section heading.",
"type": "string"
},
"text": {
"type": "string",
"description": "Short verbatim excerpt (whitespace-collapsed) containing the value."
},
"startOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Start character offset of the matched value in the extracted text."
},
"endOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"text",
"startOffset",
"endOffset"
],
"additionalProperties": false
}
},
"required": [
"requirement",
"category",
"mandatory",
"confidence"
],
"additionalProperties": false
}
},
"deadlines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string"
},
"date": {
"description": "ISO date when the deadline is a calendar date.",
"type": "string"
},
"relative": {
"description": "Relative deadline as written, e.g. \"within 30 days of receipt of invoice\".",
"type": "string"
},
"description": {
"type": "string"
},
"confidence": {
"type": "number",
"minimum": 0,
"maximum": 1
},
"sourceEvidence": {
"type": "object",
"properties": {
"page": {
"description": "1-based page number — present only when the source has real page boundaries (never inferred).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"section": {
"description": "Nearest preceding section heading.",
"type": "string"
},
"text": {
"type": "string",
"description": "Short verbatim excerpt (whitespace-collapsed) containing the value."
},
"startOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Start character offset of the matched value in the extracted text."
},
"endOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"text",
"startOffset",
"endOffset"
],
"additionalProperties": false
}
},
"required": [
"type",
"description",
"confidence"
],
"additionalProperties": false
}
},
"riskFlags": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "Observable condition, e.g. automatic_renewal, missing_expiry_date, contradictory_amounts, unlimited_liability_language, embedded_instructions_detected."
},
"severity": {
"type": "string",
"enum": [
"low",
"medium",
"high"
]
},
"reason": {
"type": "string",
"description": "The observable condition in the document — never a legal conclusion."
},
"sourceEvidence": {
"type": "object",
"properties": {
"page": {
"description": "1-based page number — present only when the source has real page boundaries (never inferred).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"section": {
"description": "Nearest preceding section heading.",
"type": "string"
},
"text": {
"type": "string",
"description": "Short verbatim excerpt (whitespace-collapsed) containing the value."
},
"startOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Start character offset of the matched value in the extracted text."
},
"endOffset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"text",
"startOffset",
"endOffset"
],
"additionalProperties": false
}
},
"required": [
"type",
"severity",
"reason"
],
"additionalProperties": false
}
},
"metadata": {
"type": "object",
"properties": {
"pageCount": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"characterCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"wordCount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"format": {
"type": "string",
"enum": [
"pdf",
"docx",
"html",
"text",
"markdown",
"csv"
]
},
"source": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"url",
"text"
]
},
"url": {
"type": [
"string",
"null"
]
},
"contentType": {
"type": [
"string",
"null"
]
},
"byteLength": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"required": [
"kind",
"url",
"contentType",
"byteLength"
],
"additionalProperties": false
},
"pageProvenance": {
"type": "boolean",
"description": "true when evidence page numbers come from real page boundaries."
},
"extractionMode": {
"type": "string",
"enum": [
"auto",
"requested_only"
]
},
"extractionMethod": {
"type": "string",
"enum": [
"deterministic",
"deterministic+llm_verified"
]
},
"llmAssist": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"not_configured",
"disabled",
"not_needed",
"used",
"failed"
]
},
"verifiedFacts": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"rejectedFacts": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991,
"description": "LLM proposals discarded because their quote was not found verbatim in the document or did not support the value."
}
},
"required": [
"status",
"verifiedFacts",
"rejectedFacts"
],
"additionalProperties": false
},
"extractorVersion": {
"type": "string"
}
},
"required": [
"pageCount",
"characterCount",
"wordCount",
"format",
"source",
"pageProvenance",
"extractionMode",
"extractionMethod",
"llmAssist",
"extractorVersion"
],
"additionalProperties": false
},
"warnings": {
"type": "array",
"items": {
"type": "string"
}
},
"overallConfidence": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Overall extraction certainty for this document (text quality × fact coverage × fact confidence). Not a measure of business risk."
},
"limitations": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"documentType",
"documentSubtype",
"documentTypeConfidence",
"documentTypeSource",
"language",
"title",
"facts",
"requestedFacts",
"entities",
"dates",
"amounts",
"percentages",
"obligations",
"requirements",
"deadlines",
"riskFlags",
"metadata",
"warnings",
"overallConfidence",
"limitations"
],
"additionalProperties": false
}Category: Document Intelligence · hierarchy: primary · idempotent: yes · side effects: no