> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract Quickstart

> Extract structured data from your document

**Extract** returns selected fields from a document as structured JSON that matches your schema.

In this quickstart, you will:

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

## Before you start

You need:

* TextIn API credentials. See [Authentication](/xparse/authentication).
* Python 3.8 or later.
* A document that contains the fields you want to extract.

<Info>
  For supported formats, file size limits, page limits, and concurrency limits, see [Supported Files & Limits](/xparse/supported-files).
</Info>

## Install dependencies

```bash theme={null}
pip install requests
```

## Set your credentials

```bash theme={null}
export TEXTIN_APP_ID="your-app-id"
export TEXTIN_SECRET_CODE="your-secret-code"
```

On Windows PowerShell:

```powershell theme={null}
$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.

```json theme={null}
{
  "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.

<Info>
  See [Schema Guide](/xparse/extract/schema-guide) for field types, nested objects, arrays, and schema limits.
</Info>

## Send an extraction request

```python theme={null}
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"]`:

```json theme={null}
{
  "invoice_number": "INV-2024-001",
  "vendor_name": "Acme Corp",
  "total_amount": 1250.0
}
```

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

## Use cURL

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

```bash theme={null}
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](/xparse/extract/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.

<Info>
  See [Best Practices](/xparse/extract/best-practices) for more guidance.
</Info>

## Next steps

<CardGroup cols={3}>
  <Card title="Schema Guide" icon="book" href="/xparse/extract/schema-guide">
    Create and export extraction schemas.
  </Card>

  <Card title="Response Format" icon="code" href="/xparse/extract/response-format">
    Understand extracted data, citations, page-level fields, and usage fields.
  </Card>

  <Card title="Best Practices" icon="lightbulb" href="/xparse/extract/best-practices">
    Improve schema quality and extraction accuracy.
  </Card>
</CardGroup>