Schema-driven PDF extraction returns typed JSON with per-field confidence. Here is the pattern, the failure modes, and the credit math.

You extract structured JSON from a PDF by posting the file plus a JSON schema to a schema-driven extraction endpoint. The endpoint runs a large language model against the PDF text and returns typed values plus a confidence score per field, so your code can decide whether to accept, retry, or route to human review. On ASHDOCS, this is POST /api/v1/extract/data, 3 credits per document, with per-field confidence and cross-field validation.

How does schema-driven PDF extraction actually work?

What does the request look like?

Send multipart/form-data with the file, a JSON schema field, and an optional confidence_threshold. The schema is a plain object where each key defines a target field and its expected type.

curl -X POST https://www.ashdocs.com/api/v1/extract/data \
  -H "X-API-Key: ash_test_xxxxxxxx" \
  -F "file=@invoice.pdf" \
  -F 'schema={
    "invoice_number":  { "type": "string" },
    "invoice_date":    { "type": "date" },
    "total_amount":    { "type": "number" },
    "line_items": {
      "type": "array",
      "items": { "description": { "type": "string" }, "amount": { "type": "number" } }
    }
  }' \
  -F "confidence_threshold=0.85"

What does the response look like?

{
  "job_id": "job_01H...",
  "status": "completed",
  "extracted_json": {
    "invoice_number": "INV-2026-0042",
    "invoice_date": "2026-01-31",
    "total_amount": 1240.50,
    "line_items": [
      { "description": "Consulting — Jan", "amount": 1200.00 },
      { "description": "Rush fee",         "amount":   40.50 }
    ]
  },
  "confidence": {
    "invoice_number": 0.98,
    "invoice_date":   0.94,
    "total_amount":   0.97,
    "line_items":     0.91
  },
  "confidence_summary": { "overall": 0.95, "min": 0.91, "flagged": 0, "total": 4 },
  "needs_review": false
}

When should I route to human review instead of accepting the JSON?

How much does one extraction cost?

extract/data costs 3 credits per document regardless of page count. Test keys (ash_test_*) never charge — use them in CI and for tuning schemas. Live keys deduct from your monthly plan; see /pricing for tier detail.

Frequently asked questions

What file types does the extraction endpoint accept?

PDF is the primary target. Scanned PDFs run OCR first — you'll see a lower confidence floor and slightly longer p95 latency. Images (JPEG, PNG) are converted to PDF transparently before extraction.

Can I extract data without storing the source PDF?

Yes. Set options.retention="zero" on the request or toggle account-wide zero-retention. Confidence and extracted JSON are still returned inline; the source PDF and the extracted result are not persisted.

What LLM does ASHDOCS use for schema-driven extraction?

Claude Sonnet 5 via the Emergent LLM key. The model choice is not exposed as a parameter — the endpoint is optimized end-to-end and we upgrade the underlying model without a breaking change to the API.

How do I handle low-confidence extractions programmatically?

Set on_low_confidence="fail" in the request options to have ASHDOCS return HTTP 422 with detail.code=low_confidence instead of a valid response. Alternatively, subscribe to the review.approved webhook and route flagged rows through the /review queue.

How to extract structured JSON from PDFs with an API