Extraction
Extract Data
Extract structured data from PDF documents using custom schemas
POST
Overview
The/v2/extract endpoint extracts structured data from PDF documents. It supports optional bounding box citations and handles large documents efficiently.
The endpoint returns a job ID for asynchronous processing. Use the job management endpoints to check status and retrieve results.
Request
The PDF or image (PNG, JPEG, TIFF, WebP) to process for data extraction. Maximum file size: 500MB. Either
pdf_file or file_url must be provided.JSON schema defining the structure and fields to extract from the document. Must be a valid JSON Schema format with type definitions, properties, and required fields.
Extraction mode preset:
basic or agentic. A mode applies a recommended extraction configuration, so you don’t have to tune each setting yourself. Omit to use the default configuration.Return bounding box coordinates for extracted values. When enabled, each extracted field includes a
citation object with precise location data in the source document.Run a pre-flight PII check before extraction. If PII is found, no extraction job is created and the endpoint returns HTTP 200 with
"status": "pii_blocked" and "blocked": true in the body, so check those fields before polling.Apply your organization’s saved rules to the schema fields they act on. Every value a rule changed carries a memory note saying which rule changed it and what was originally extracted, and the job’s
metadata.memory lists the rules that acted and any that could not, with the reason. Requires memory to be enabled for your organization.Response
PII-Blocked Response
Whendetect_pii is enabled and PII is found, the endpoint returns HTTP 200 with no job created. Check status and blocked to tell this apart from a normal submission:
Extraction Results Format
Once the job is completed, the results will contain the extracted data with additional metadata:Where the value was found.
null when citations are disabled or the value could not be grounded:Example Extraction Results
For a simple financial document schema:Schema
Extraction Results
Citations
Theenable_citations parameter controls whether bounding box coordinates are returned with extracted data. Citations provide references back to the source document, allowing you to trace where each extracted value was found.
With Citations Enabled
Whenenable_citations is set to True, each extracted field includes a citation object with precise location data (or null when the value could not be grounded):
bbox:[left, top, right, bottom]in PDF point space (origin: top-left)- Standard A4 page = 595 x 842 points
page_width/page_heightincluded for scaling to any display size
Without Citations (Default)
Whenenable_citations is False (default), no grounding pass runs. Each field still uses the nested shape, with grounding_score: 0.0 and citation: null:
Set
enable_citations to True when you need to trace extracted values back to their exact location in the document, such as for UI highlighting or audit trails.JSON Schema Definition
Theschema_data parameter must be a valid JSON Schema that defines the structure of data to extract. All schemas must follow the JSON Schema specification with proper type definitions, properties, and constraints.
Basic Schema Structure
All extraction schemas must include:type: “object” (root level)properties: Object defining the fields to extractrequired: Array of required field namesadditionalProperties: Set toFalsefor strict validation
Financial Document Schema Example
This example demonstrates extracting shareholding patterns and board information from financial documents:Advanced Financial Schema Example
This example shows a more complex schema for extracting detailed shareholding information:Citation Extraction Schema
Legal Document Schema
JSON Schema Field Types
Job Management Integration
After creating an extraction job, you can poll for completion using the job status endpoints:Advanced Schema Patterns
Nested Object Structures
For complex documents with hierarchical data:Array of Complex Objects
For extracting lists of structured data:Error Handling
Body
multipart/form-data
Apply your organization's saved rules to the schema fields they act on. Every value a rule changed carries a memory note saying which rule changed it and what was originally extracted, and the job's metadata.memory lists the rules that acted and any that could not, with the reason. Requires memory to be enabled for your organization. Defaults to false.

