Extract Quickstart

Extract returns selected fields from a document as structured JSON that matches your schema. In this quickstart, you will:

Define a small extraction schema.
Send an extraction request with Python.
Read the structured JSON returned by Extract.

Before you start

You need:

TextIn API credentials. See Authentication.
Python 3.8 or later.
A document that contains the fields you want to extract.

For supported formats, file size limits, page limits, and concurrency limits, see Supported Files & Limits.

Install dependencies

pip install requests

Set your credentials

export TEXTIN_APP_ID="your-app-id"
export TEXTIN_SECRET_CODE="your-secret-code"

On Windows PowerShell:

$env:TEXTIN_APP_ID="your-app-id"
$env:TEXTIN_SECRET_CODE="your-secret-code"

Define the fields to extract

Create a schema that describes the fields you need. The examples in this page use the schema JSON format accepted by Extract.

{
  "type": "object",
  "properties": {
    "invoice_number": {
      "type": ["string", "null"],
      "description": "The invoice number"
    },
    "vendor_name": {
      "type": ["string", "null"],
      "description": "The vendor or merchant name"
    },
    "total_amount": {
      "type": ["number", "null"],
      "description": "The total amount including tax"
    }
  },
  "required": ["invoice_number", "vendor_name", "total_amount"]
}

In a schema:

The property name becomes the output field name.
type defines the expected value type.
description helps the extraction model identify the correct value in the document.

See Schema Guide for field types, nested objects, arrays, and schema limits.

Send an extraction request

import base64
import json
import os
import requests

schema = {
    "type": "object",
    "properties": {
        "invoice_number": {
            "type": ["string", "null"],
            "description": "The invoice number",
        },
        "vendor_name": {
            "type": ["string", "null"],
            "description": "The vendor or merchant name",
        },
        "total_amount": {
            "type": ["number", "null"],
            "description": "The total amount including tax",
        },
    },
    "required": ["invoice_number", "vendor_name", "total_amount"],
}

with open("invoice.pdf", "rb") as file:
    file_base64 = base64.b64encode(file.read()).decode("utf-8")

response = requests.post(
    "https://api.textin.ai/ai/service/v3/entity_extraction",
    headers={
        "x-ti-app-id": os.environ["TEXTIN_APP_ID"],
        "x-ti-secret-code": os.environ["TEXTIN_SECRET_CODE"],
        "Content-Type": "application/json",
    },
    json={
        "file": {"file_base64": file_base64},
        "schema": schema,
        "parse_options": {"parse_mode": "auto"},
        "extract_options": {"generate_citations": False},
    },
)

response.raise_for_status()
result = response.json()["result"]

print(json.dumps(result["extracted_schema"], indent=2, ensure_ascii=False))

Read the extracted data

Extract returns structured JSON in result["extracted_schema"]:

{
  "invoice_number": "INV-2024-001",
  "vendor_name": "Acme Corp",
  "total_amount": 1250.0
}

In current Extract responses, missing string fields will be returned as empty strings, and missing array fields may be returned as empty arrays.

Use cURL

For a lightweight cURL example, use a hosted file URL:

curl -X POST "https://api.textin.ai/ai/service/v3/entity_extraction" \
  -H "x-ti-app-id: $TEXTIN_APP_ID" \
  -H "x-ti-secret-code: $TEXTIN_SECRET_CODE" \
  -H "Content-Type: application/json" \
  -d '{
    "file": {
      "file_url": "https://example.com/invoice.pdf"
    },
    "schema": {
      "type": "object",
      "properties": {
        "invoice_number": {
          "type": ["string", "null"],
          "description": "The invoice number"
        },
        "total_amount": {
          "type": ["number", "null"],
          "description": "The total amount including tax"
        }
      },
      "required": ["invoice_number", "total_amount"]
    },
    "extract_options": {
      "generate_citations": false
    }
  }'

Get source citations

Enable citations when you need to show where an extracted value came from. Citations can include:

Page number
Source text
Bounding box coordinates

When enabled, citations are returned in result["citations"]. See Response Format for the citation structure.

Improve extraction quality

Use field names that match the wording in the source document.
Add clear field descriptions.
Use enums when the possible values are known.
Keep schemas as simple as possible.
Avoid asking the schema to calculate values that can be computed downstream.

See Best Practices for more guidance.

Next steps

Schema Guide

Create and export extraction schemas.

Response Format

Understand extracted data, citations, page-level fields, and usage fields.

Best Practices

Improve schema quality and extraction accuracy.

Getting Started

Parse

Extract

Before you start

Install dependencies

Set your credentials

Define the fields to extract

Send an extraction request

Read the extracted data

Use cURL

Get source citations

Improve extraction quality

Next steps

Schema Guide

Response Format

Best Practices

​Before you start

​Install dependencies

​Set your credentials

​Define the fields to extract

​Send an extraction request

​Read the extracted data

​Use cURL

​Get source citations

​Improve extraction quality

​Next steps

Schema Guide

Response Format

Best Practices

Before you start

Install dependencies

Set your credentials

Define the fields to extract

Send an extraction request

Read the extracted data

Use cURL

Get source citations

Improve extraction quality

Next steps