Introduction

Extract structured, schema-validated data from PDFs, images, and Office documents with the Talonic REST API: one HTTPS call, JSON out, per-field confidence.

The Talonic API is a document data extraction API: it turns PDFs, scans, images, Word documents, spreadsheets, and plain text into structured, schema-validated JSON with a single REST call. You send a file to POST /v1/extract, optionally with a schema describing the fields you want, and receive the extracted values back with per-field confidence scores.

Base URL: https://api.talonic.com | Protocol: HTTPS + JSON | Auth: Bearer tlnc_...

Most integrations start with POST /v1/extract — the quick extract endpoint — to submit a document and receive structured fields back. A typical workflow is: create an API key, upload a file with an optional schema, and consume the JSON response with per-field confidence scores and cost headers.

curl -X POST https://api.talonic.com/v1/extract \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -F "file=@invoice.pdf"

The API supports three extraction modes: auto-detect (no schema, discovers all fields), schema-driven (returns exactly the fields you define), and query (filter previously extracted data without re-processing). Extraction responses include a request_id in the body, and every API response carries an X-Request-Id header — quote either when contacting support, and both are logged so a failed call can always be traced.

Beyond quick extraction, the API has a governed tier: configure a Spec (a schema plus a composed pipeline rail of resolution policies and validation gates) in the app, then run it over documents with [POST /v1/run](run-spec) (upload and run in one call) or [POST /v1/pipelines](run-pipeline) (documents already on the platform). Pipelines add review holdback, per-cell provenance, and data-product delivery on top of raw extraction. And once documents are ingested, [POST /v1/ask](post-ask) answers natural-language questions over the whole corpus with cited, verified answers.

Pair the extract endpoint with GET /v1/documents and GET /v1/extractions to manage your document library and retrieve results later. Webhook callbacks via extraction.complete events eliminate the need for polling on async extractions.

Cost is transparent on every call: synchronous extraction responses carry X-Talonic-Cost-Credits, X-Talonic-Cost-EUR, and X-Talonic-Balance-Credits headers, and every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset so your client can meter itself. Fields resolved from the field registry cost nothing; only AI-resolved fields consume credits. When your balance runs out, write calls return 402 insufficient_credits before any work starts.

{
  "extraction_id": "d1a2b3c4-5678-9abc-def0-1234567890ab",
  "request_id": "req_x7y8z9a0b1c2d3e4",
  "status": "complete",
  "document": { "id": "f0e1d2c3-b4a5-9687-8765-432109876543", "filename": "invoice.pdf", "pages": 2, "type_detected": "Invoice" },
  "data": {
    "vendor_name": "Acme GmbH",
    "invoice_number": "INV-2025-0042",
    "total_amount": 14250.00
  },
  "confidence": { "overall": 0.96, "fields": { "vendor_name": 0.97, "invoice_number": 0.99, "total_amount": 0.94 } }
}