Extract

Introduction

The extract method in Retab’s document processing pipeline uses AI models to extract structured data from any document based on a provided JSON schema. This endpoint is ideal for automating data extraction tasks, such as pulling key information from invoices, forms, receipts, images, or scanned documents, for use in workflows like data entry automation, analytics, or integration with databases and applications.

The typical extraction workflow follows these steps:

1. Schema Definition: Define a JSON schema that describes the structure of the data you want to extract.
2. Extraction: Use Retab’s extract method to process the document and retrieve structured data.
3. Validation & Usage: Validate the extracted data (optionally using likelihood scores) and integrate it into your application.

The SDKs already help here:

• Python parses message.parsed against the JSON schema you pass in
• Node accepts a JSON schema object, a schema file path, or a zod schema directly

You can still add your own application-level validation if you want stricter business rules.

Unlike the parse method that focuses on raw text extraction, extract provides:

• Structured Output: Data extracted directly into JSON format matching your schema.
• AI-Powered Inference: Handles complex layouts, handwritten text, and contextual understanding.
• Modality Support: Works with text, images, or native document formats.
• Consensus Mode: Optional multi-run consensus for higher accuracy on ambiguous documents.
• Likelihood Scores: Provides likelihood scores for each extracted field.
• Batch Processing Ready: Efficient for high-volume extraction tasks.

Extract API

ExtractRequest · ExtractRequest

Show properties

document · string | object · required

The document to extract from. Can be a file path (string), or an object with filename (string) and url (string, e.g., base64-encoded data).

model · string · required

The AI model to use for extraction. Examples: retab-small for balanced accuracy and speed.

json_schema · object · required

The JSON schema defining the structure of the extracted data. Includes properties, required fields, and optional X-SystemPrompt for custom instructions.

image_resolution_dpi · integer · default: "192"

The DPI of the image sent to the LLM. Defaults to 192.

chunking_keys · dict[str, str] | None · default: "None"

If set, keys to be used for the extraction of long lists of data using Parallel OCR. Defaults to None.

metadata · dict[str, str] · default: "{}"

User-defined metadata to associate with this extraction. Defaults to .

n_consensus · integer · default: "1"

Number of consensus runs. Set to >1 for multi-run averaging to improve accuracy on uncertain extractions (increases cost).

additional_messages · list[ChatCompletionRetabMessage] · default: "null"

Additional chat messages to append after the document content. Useful for extra context, clarifications, or domain-specific instructions. Roles follow the chat message format used by the SDKs, including system, developer, user, and assistant.

Returns · RetabParsedChatCompletion

A RetabParsedChatCompletion with the extracted data, usage details, likelihood scores, and a persisted extraction_id.

Show properties

id · string

Unique identifier for the completion.

choices · array[object]

Array of completion choices. choices[0].message.parsed contains the structured output.

usage · object

Token usage details.

likelihoods · object | null

Confidence scores for each extracted field.

extraction_id · string | null

Identifier for the stored extraction record, usable with client.extractions.*.

Python

from retab import Retab

client = Retab()

# Use client.documents.extract_stream(...) for stream mode
doc_msg = client.documents.extract(
    document = "freight/booking_confirmation.jpg", 
    model="retab-micro",
    json_schema = {
      'X-SystemPrompt': 'You are a useful assistant.',
      'properties': {
          'name': {
              'description': 'The name of the calendar event.',
              'title': 'Name',
              'type': 'string'
          },
          'date': {
              'description': 'The date of the calendar event in ISO 8601 format.',
              'title': 'Date',
              'type': 'string'
          }
      },
      'required': ['name', 'date'],
      'title': 'CalendarEvent',
      'type': 'object'
    },
    n_consensus=1 # 1 means disabled (default), if greater than 1 it will run the extraction with n-consensus mode
)

print(doc_msg.data)
print(doc_msg.likelihoods)
print(doc_msg.extraction_id)

Use Case: Extracting Event Information from Documents

Extract structured calendar event data from a booking confirmation image and validate likelihood scores before saving to a database.

Python

from retab import Retab

client = Retab()

# Extract data
result = client.documents.extract(
    document="freight/booking_confirmation.jpg",
    model="retab-micro",
    json_schema={
        'X-SystemPrompt': 'You are a useful assistant.',
        'properties': {
            'name': {
                'description': 'The name of the calendar event.',
                'title': 'Name',
                'type': 'string'
            },
            'date': {
                'description': 'The date of the calendar event in ISO 8601 format.',
                'title': 'Date',
                'type': 'string'
            }
        },
        'required': ['name', 'date'],
        'title': 'CalendarEvent',
        'type': 'object'
    },
    n_consensus=1
)

# Python SDK parses against the schema automatically
extracted_data = result.data
likelihoods = result.likelihoods or {}

if extracted_data is None:
    print("Schema validation failed")
else:
    print(f"Extracted Event: {extracted_data.name} on {extracted_data.date}")

    if all(score > 0.7 for score in likelihoods.values()):
        print("High likelihood extraction - Saving to DB...")
    else:
        print("Low likelihood - Review manually")

print(f"Processed with {result.usage.total_tokens} tokens")

Use Case: Using Additional Messages for Context

Use additional_messages to provide extra context or specific instructions that help guide the extraction. This is useful when you need to clarify ambiguous fields, provide domain-specific knowledge, or correct the model’s behavior.

Python

from retab import Retab

client = Retab()

# Extract invoice data with additional context
result = client.documents.extract(
    document="invoices/invoice_001.pdf",
    model="retab-micro",
    json_schema={
        'properties': {
            'vendor_name': {'type': 'string', 'description': 'Name of the vendor'},
            'invoice_number': {'type': 'string', 'description': 'Invoice number'},
            'total_amount': {'type': 'number', 'description': 'Total amount due'},
            'currency': {'type': 'string', 'description': 'Currency code (e.g., USD, EUR)'}
        },
        'required': ['vendor_name', 'invoice_number', 'total_amount'],
        'type': 'object'
    },
    additional_messages=[
        {
            "role": "developer",
            "content": "Extract values exactly as written. Do not infer missing currency."
        },
        {
            "role": "user",
            "content": "Note: This invoice is from our European supplier. Amounts should be in EUR unless explicitly stated otherwise."
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://www.example.com/logo.png",
                        "detail": "auto"
                    }
                }
            ]
        }
    ]
)

print(result.data)

Metadata Filters

Use metadata at extraction time to tag each document with stable identifiers, then filter those extractions later using the same keys.

This is especially important in multi-tenant systems: always include stable tenant-scoping metadata keys to avoid cross-tenant contamination.

1. Tag the extraction request with metadata

Python

from retab import Retab

client = Retab()

result = client.documents.extract(
    document="freight/booking_confirmation.jpg",
    model="retab-small",
    json_schema=my_schema,
    metadata={
        "organization_id": "org_123",
        "source": "sinari_jobs",
        "project_id": "project_abc",
    },
)

2. Filter extractions by metadata

Python

from retab import Retab

client = Retab()

tenant_extractions = client.extractions.list(
    limit=50,
    metadata={
        "organization_id": "org_123",
        "source": "sinari_jobs",
    },
)

When multiple metadata keys are provided, all keys are applied together as exact-match filters.

Best Practices

Model Selection

• retab-large: Use for complex documents requiring deep contextual understanding.
• retab-small: Balanced for accuracy and cost, recommended for most extraction tasks.
• retab-micro: Faster and cheaper for simple extractions or high-volume processing.

Schema Design

• Keep schemas concise: Only include required fields to improve extraction accuracy.
• Use descriptive description fields: Helps the AI model understand what to extract.
• Add X-SystemPrompt for custom guidance: E.g., “Focus on freight details” for domain-specific extractions.

Confidence Handling

• Set a threshold (e.g., 0.7) for automated processing.
• For critical tasks, enable n_consensus > 1 to average results and boost reliability.

Using Additional Messages

• Use additional_messages to provide domain-specific context or clarifications.
• Prefer developer or system messages for extraction policy and user messages for document-specific context.
• Ideal for: currency defaults, date format preferences, handling ambiguous abbreviations, or specifying regional conventions.
• Keep messages concise to avoid diluting the extraction focus.

# Create messages from a reference document

# Use those messages as additional context for extraction
result = client.documents.extract(
    document="invoices/invoice_001.pdf",
    json_schema=my_schema,
    model="retab-small",
    additional_messages=[{
        "role": "user",
        "content": "Note: This invoice is from our European supplier. Amounts should be in EUR unless explicitly stated otherwise."
    }]
)