Extract Data from Document
talonic_extractExtract structured, schema-validated JSON from a document: PDF, scan, image, DOCX, email, or photo. Returns the requested fields with per-field confidence scores.
USE WHEN: the user asks to extract data from a document, turn a PDF into JSON, pull fields from a file, or parse a scan / form / statement / receipt / report, for common (invoice, contract) or unusual document types.
NOT FOR: full plain text (use talonic_to_markdown) · finding documents (use talonic_search / talonic_filter).
BY NAME: if the user names a file, call talonic_search first to get its document_id, then call this.
ARGS: define the fields you want with inline schema (JSON Schema, e.g. {type:'object',properties:{vendor_name:{type:'string'}}}) OR a saved schema_id, not both. Don't know the fields yet? Set auto_schema:true to let Talonic discover them (open capture) and return a suggested schema you can refine. Provide EXACTLY ONE document source: document_id (cheapest, a workspace doc), file_url (public URL), or file_data+filename (small local files only).
COST: each call uses credits; talonic_get_balance shows the remaining balance.
RETURNS: data (the JSON), confidence.overall and confidence.fields (treat <0.7 as needs review), document metadata, extraction_id.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| schema | No | Inline schema definition. REQUIRED unless `schema_id` is provided. Recommended: full JSON Schema {type:'object', properties:{...}}. Also accepted: flat key-type map {field_name:'string', amount:'number'}. Mutually exclusive with `schema_id`. | |
| file_url | No | URL to a document file. The Talonic API fetches it server-side. Use this for documents already on the public web. | |
| filename | No | Original filename including extension, e.g. 'invoice.pdf'. Used to infer MIME type when uploading via `file_data`. Required when `file_data` is provided. | |
| file_data | No | Base64-encoded file bytes. Recommended path when the agent already has the file in memory (e.g., the user attached a PDF to the conversation). Pair with `filename` so MIME type can be inferred. Works regardless of where the file lives on disk. | |
| file_path | No | Local path to a document file. Only works if the MCP server has read access to that path. In sandboxed chat clients (Claude Desktop, Cowork) where uploads land in a host-owned directory, use `file_data` instead. | |
| schema_id | No | ID of a saved schema. REQUIRED unless `schema` is provided. Accepts UUID or SCH-XXXXXXXX short id from talonic_list_schemas. Mutually exclusive with `schema`. | |
| auto_schema | No | Open capture: when true, extract WITHOUT providing a schema — Talonic discovers the document's fields and returns them plus a suggested schema you can refine and reuse. Use this when you don't yet know the fields. Mutually exclusive with `schema` and `schema_id`. | |
| document_id | No | ID of a document already in the workspace, to re-extract with a new schema. | |
| instructions | No | Natural-language guidance for the extractor, e.g. 'Focus on the billing section. Amounts are in EUR.' | |
| include_markdown | No | Include OCR-converted markdown in the response alongside structured data. | |
| include_provenance | No | Include per-field provenance (source_text, section, page) showing where each value was found in the document. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cost | No | Per-call cost and post-call balance, parsed from the X-Talonic-* response headers. `null` for non-extract calls; not always present on legacy clients. | |
| data | Yes | The extracted structured data, shape determined by the schema. | |
| links | No | URLs for self, document, and human-readable dashboard view. | |
| schema | No | Schema metadata: which schema was used and how it can be saved. | |
| status | Yes | Extraction status (e.g. 'complete'). | |
| document | Yes | Metadata about the ingested document. | |
| markdown | No | OCR-converted markdown. Present only when `include_markdown: true`. | |
| confidence | No | Extraction confidence. Treat fields below ~0.7 as needing human review. | |
| processing | No | Processing metadata: duration, pages processed, region. | |
| provenance | No | Per-field source evidence (source_text, section, page). Present only when `include_provenance: true`. | |
| request_id | No | Server-assigned request ID for support and debugging. | |
| extraction_id | Yes | Stable identifier for this extraction. |