Skip to main content
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

file
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.
string
URL to a PDF file to process. Either pdf_file or file_url must be provided.
string
required
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.
string
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.
boolean
default:"false"
Return bounding box coordinates for extracted values. When enabled, each extracted field includes a citation object with precise location data in the source document.
string
Optional name identifying the schema, stored with the job for traceability.
boolean
default:"false"
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.
boolean
default:"false"
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

string
Unique identifier for the extraction job
string
Initial job status (typically “queued”)
string
Descriptive message about the job creation
number
Number of Credits remaining in your quota

PII-Blocked Response

When detect_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:
object
Each extracted field returns an object with the following structure:
string|number|array|object
The extracted value matching the schema type
object
Confidence scores for the field:
object | null
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

The enable_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

When enable_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 coordinate system:
  • bbox: [left, top, right, bottom] in PDF point space (origin: top-left)
  • Standard A4 page = 595 x 842 points
  • page_width / page_height included for scaling to any display size

Without Citations (Default)

When enable_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

The schema_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 extract
  • required: Array of required field names
  • additionalProperties: Set to False for 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

JSON Schema Field Types

string
Text content, single values. Use for names, descriptions, dates as text.
number
Numeric values, amounts, quantities. Use for counts, percentages, monetary values.
integer
Whole numbers only. Use for counts, IDs, years.
boolean
True/false values. Use for yes/no questions, flags.
array
Lists of items. Must include items property defining the type of array elements.
object
Structured data with nested fields. Must include properties defining nested structure.
null
Null values. Can be combined with other types using array notation: ["string", "null"]

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

Bad Request
Invalid JSON schema format or missing required parameters
Unauthorized
Invalid or missing API key
Payment Required
Insufficient or expired credits
Payload Too Large
File size exceeds the 500MB limit
Unprocessable Entity
Invalid file format, malformed JSON schema, or processing error
Too Many Requests
Rate limit exceeded
Internal Server Error
Server error during processing

Authorizations

api-key
string
header
required

Body

multipart/form-data
schema_data
string
required

JSON schema defining the structure and fields to extract from the document. Example: {"type":"object","properties":{"invoice_number":{"type":"string","description":"The invoice number"}},"required":["invoice_number"],"additionalProperties":false}

pdf_file
file

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.

file_url
string

URL to a PDF file to process. Either pdf_file or file_url must be provided.

mode
enum<string> | null

Extraction mode preset: basic or agentic. A mode applies a recommended extraction configuration. Omit to use the default configuration.

Available options:
basic,
agentic
enable_citations
boolean
default:false

Return bounding box coordinates for extracted values

enable_computed_fields
boolean
default:false

Beta. Calculate fields that aren't printed on the document from other extracted fields, as described in the field's schema description. Each calculated field returns a computed object with its inputs and outcome.

schema_name
string | null

Optional name identifying the schema, stored with the job for traceability.

detect_pii
boolean
default:false

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.

enable_memory
boolean
default:false

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.

Response

200 - application/json

Successful response

job_id
string

Unique identifier for the extraction job

status
string

Initial job status (typically 'queued')

message
string

Descriptive message about the job creation

quota_remaining
number

Number of Credits remaining in your quota