> This page is for version v2025-04-21.
> For other versions, use one of these documentation indexes:
> - v2026-02-09 (default): https://docs.extend.ai/2026-02-09/llms.txt
> - v2025-04-21: https://docs.extend.ai/2025-04-21/llms.txt
> - v2024-12-23: https://docs.extend.ai/2024-12-23/llms.txt

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extend.ai/llms.txt
> Use this file to discover all available pages before exploring further.
>
> ## API version
> The current API version is `2026-02-09`, served at the site root (no version prefix in URLs).
> If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version.
> Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version.
> Do not treat older-version pages as the source of truth for new integrations.

# Quick Start (5 minutes)

> Get started with Extend in under 5 minutes using your own documents and schema.

Want to see how Extend works with your own documents? This guide will get you up and running in under 5 minutes to test extraction on your files, using the API.

### Optional: Use a sample document

If you don't have a document handy, use this [Sample Invoice](https://extend-public-files.s3.us-east-2.amazonaws.com/Invoice+20193059.pdf). We'll reference it throughout the steps.

## Step 1: Import / Create Your Schema

Open the [Extend Studio](https://dashboard.extend.app/studio). In the Extractor card, click **Create new** and choose one of:

* **Import JSON Schema**: If you have an existing JSON Schema, you can import that configuration here.
* **Generate Extractor**: If you have a document (e.g., the sample invoice above), you can generate a starter schema from it.

![Create Extractor options](/_fern-files/_img/9744971324a44ca04ff084c989baa43ea2666798c630f2909deb94f9b32527a3.webp)

## Step 2: Copy the Code

Now that we have created our Extractor, we will run a document against it, via the API.

We will copy a pre-generated code snippet to execute your Extractor against a file you provide:

In the builder tab of the Extractor, click **View code** in the top-right. In the modal, pick your preferred language tab and copy the snippet.

Replace `YOUR_API_KEY` with your actual key, available in the [Developers](https://dashboard.extend.ai/developers) page.

If you have unsaved changes (there will be a warning), first click **Save** at the bottom right, so the code snippet reflects your latest config.

If you're using the JavaScript or Python SDK snippets, install the SDKs first from our [SDKs](/2025-04-21/developers/sdks) page.

We have provided example code snippets below, which look similar to what you will find on the UI using the "View code" button.

![API code example](/_fern-files/_img/eae9ec6292fb0d696a96a6770c3fdef3088e55ed6da28af5a4e070d72d6c2e46.webp)

**`TypeScript SDK`**

```typescript TypeScript SDK
import { ExtendClient } from "extend-ai";

const client = new ExtendClient({ token: "YOUR_API_KEY" });

const response = await client.processorRun.create({
  processorId: "<YOUR_PROCESSOR_ID>", // This can be retrieved in the "Overview" tab of your newly created Extractor, in the UI
  file: {
    fileUrl: "<YOUR_FILE_URL>", // You may use our sample invoice URL. Only keep one of fileUrl or fileId.
    fileId: "<YOUR_FILE_ID>" // If you uploaded a file into the Extend system, use this. Only keep one of fileId or fileUrl.
  },
  sync: true,
  config: {
    // Put your config here, or copy our sample invoice config below
  }
});

console.log("Processor run:", response)
```

**`TypeScript`**

```typescript TypeScript
const response = await fetch("https://api.extend.ai/processor_runs", {
  method: "POST",
  headers: {
    "x-extend-api-version": "2025-04-21",
    "Authorization": "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    processorId: "<YOUR_PROCESSOR_ID>", // This can be retrieved in the "Overview" tab of your newly created Extractor, in the UI
    file: {
      fileUrl: "<YOUR_FILE_URL>", // You may use our sample invoice URL. Only keep one of fileUrl or fileId.
      fileId: "<YOUR_FILE_ID>", // If you uploaded a file into the Extend system, use this. Only keep one of fileId or fileUrl.
    },
    sync: true,
    config: {
      // Put your config here, or copy our sample invoice config below
    },
  }),
});

const data = await response.json();
console.log("Processor run:", data);
```

**`Python SDK`**

```python Python SDK
from extend_ai import Extend

client = Extend(token="YOUR_API_KEY")

response = client.processor_run.create(
    processor_id="<YOUR_PROCESSOR_ID>", # This can be retrieved in the "Overview" tab of your newly created Extractor, in the UI
    file={
      "fileUrl": "<YOUR_FILE_URL>", # You may use our sample invoice URL. Only keep one of fileUrl or fileId.
      "fileId": "<YOUR_FILE_ID>" # If you uploaded a file into the Extend system, use this. Only keep one of fileId or fileUrl.
    },
    sync=True,
    config={
      # Put your config here, or copy our sample invoice config below
    }
)

print("Processor run:", response)
```

**`Python`**

```python Python
import requests

response = requests.post(
    "https://api.extend.ai/processor_runs",
    json={
        "processorId": "<YOUR_PROCESSOR_ID>", # This can be retrieved in the "Overview" tab of your newly created Extractor, in the UI
        "file": {
          "fileUrl": "<YOUR_FILE_URL>", # You may use our sample invoice URL. Only keep one of fileUrl or fileId.
          "fileId": "<YOUR_FILE_ID>" # If you uploaded a file into the Extend system, use this. Only keep one of fileId or fileUrl.
        },
        "sync": True,
        "config": {
          # Put your config here, or copy our sample invoice config below
        }
    },
    headers={
        "x-extend-api-version": "2025-04-21",
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json",
    },
)

print("Processor run:", response.json())
```

**`Java SDK`**

```java Java SDK
import ai.extend.ExtendClient;

ExtendClient client = new ExtendClient("<YOUR_API_KEY>");

ProcessorRunCreateRequest runReq = ProcessorRunCreateRequest.builder()
    .processorId("<YOUR_PROCESSOR_ID>")
    .file(ProcessorRunFileInput.builder()
        .fileUrl("<YOUR_FILE_URL>") // You may use our sample invoice URL. Only keep one of fileUrl or fileId.
        .fileId("<YOUR_FILE_ID>") // If you uploaded a file into the Extend system, use this. Only keep one of fileId or fileUrl.
        .build())
    .build();
ProcessorRunCreateResponse run = client.processorRun().create(runReq);

System.out.println("Processor run: " + run);
```

If you are following along with the sample invoice, your generated config should look something like this:

**`Invoice Sample config (Typescript)`**

```json Invoice Sample config (Typescript)
"config": {
    "type": "EXTRACT",
    "baseProcessor": "extraction_performance",
    "baseVersion": "4.1.1",
    "schema": {
      "type": "object",
      "required": [
        "bill_to",
        "ship_to",
        "due_date",
        "line_items",
        "tax_amount",
        "balance_due",
        "vendor_name",
        "invoice_date",
        "total_amount",
        "invoice_number",
        "subtotal_amount"
      ],
      "properties": {
        "bill_to": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name and address of the individual or organization being billed. This is the recipient of the invoice and payment request. May appear under labels such as 'Bill To', 'Billed To', or similar."
        },
        "ship_to": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name and address where goods or services are to be delivered, if different from the billing address. May be labeled as 'Ship To', 'Shipping Address', or similar."
        },
        "due_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "The date by which payment for this invoice is expected. May be explicitly labeled as 'Due Date', 'Payment Due', or may require calculation based on payment terms. The key is identifying when the payment obligation becomes due.",
          "extend:type": "date"
        },
        "line_items": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "amount",
              "quantity",
              "unit_price",
              "description"
            ],
            "properties": {
              "amount": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The total cost for this line item, typically calculated as quantity multiplied by unit price. May also be labeled as 'Amount', 'Line Total', or similar."
              },
              "quantity": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The number of units, items, or hours billed for this line item. Can be a whole number or decimal."
              },
              "unit_price": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The price per single unit of this item before quantity multiplication. Represents the base rate for one unit."
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A description of the product or service provided in this line item. May include item names, service details, or product codes."
              }
            },
            "additionalProperties": false
          },
          "description": "The individual products, services, or charges that make up this invoice. Each item typically includes a description, quantity, unit price, and total amount. Format may vary from tables to lists."
        },
        "tax_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The total tax applied to this invoice. May be labeled as 'Tax', 'Sales Tax', or include a percentage. Represents the sum of all taxes charged.",
          "extend:type": "currency",
          "additionalProperties": false
        },
        "balance_due": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The outstanding amount that remains to be paid on this invoice. May be labeled as 'Balance Due', 'Amount Due', or similar. In some documents, this may be the same as the total amount if no prior payments or credits have been applied.",
          "extend:type": "currency",
          "additionalProperties": false
        },
        "vendor_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name of the company or individual issuing the invoice. This is the party requesting payment, often found at the top or in a header section."
        },
        "invoice_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "The date when this invoice was created or issued. This is the official date for accounting and payment term calculations. May be labeled as 'Date', 'Invoice Date', or similar, and can appear in various formats.",
          "extend:type": "date"
        },
        "total_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The final amount owed by the customer, including all items, taxes, and adjustments. This is the complete payment obligation. May be labeled as 'Total', 'Amount Due', 'Balance Due', or similar, and is often the most prominent monetary value on the document.",
          "extend:type": "currency",
          "additionalProperties": false
        },
        "invoice_number": {
          "type": [
            "string",
            "null"
          ],
          "description": "The unique identifier assigned to this invoice or billing document. This is the primary reference number for the transaction and may include numbers, letters, or special characters. Common labels include 'Invoice #', 'Bill Number', or may appear as a prominent number near the top or center of the document."
        },
        "subtotal_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The sum of all line item amounts before taxes, discounts, or additional charges. May be labeled as 'Subtotal' or similar. Represents the total of goods and services prior to adjustments.",
          "extend:type": "currency",
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "advancedOptions": {
      "citationsEnabled": true,
      "chunkingOptions": {},
      "advancedFigureParsingEnabled": true
    }
  }
```

**`Invoice Sample config (Python SDK)`**

```python Invoice Sample config (Python SDK)
config={
    "type": "EXTRACT",
    "baseProcessor": "extraction_performance",
    "baseVersion": "4.1.1",
    "schema": {
      "type": "object",
      "required": [
        "bill_to",
        "ship_to",
        "due_date",
        "line_items",
        "tax_amount",
        "balance_due",
        "vendor_name",
        "invoice_date",
        "total_amount",
        "invoice_number",
        "subtotal_amount"
      ],
      "properties": {
        "bill_to": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name and address of the individual or organization being billed. This is the recipient of the invoice and payment request. May appear under labels such as 'Bill To', 'Billed To', or similar."
        },
        "ship_to": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name and address where goods or services are to be delivered, if different from the billing address. May be labeled as 'Ship To', 'Shipping Address', or similar."
        },
        "due_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "The date by which payment for this invoice is expected. May be explicitly labeled as 'Due Date', 'Payment Due', or may require calculation based on payment terms. The key is identifying when the payment obligation becomes due.",
          "extend:type": "date"
        },
        "line_items": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "amount",
              "quantity",
              "unit_price",
              "description"
            ],
            "properties": {
              "amount": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The total cost for this line item, typically calculated as quantity multiplied by unit price. May also be labeled as 'Amount', 'Line Total', or similar."
              },
              "quantity": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The number of units, items, or hours billed for this line item. Can be a whole number or decimal."
              },
              "unit_price": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The price per single unit of this item before quantity multiplication. Represents the base rate for one unit."
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A description of the product or service provided in this line item. May include item names, service details, or product codes."
              }
            },
            "additionalProperties": False
          },
          "description": "The individual products, services, or charges that make up this invoice. Each item typically includes a description, quantity, unit price, and total amount. Format may vary from tables to lists."
        },
        "tax_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The total tax applied to this invoice. May be labeled as 'Tax', 'Sales Tax', or include a percentage. Represents the sum of all taxes charged.",
          "extend:type": "currency",
          "additionalProperties": False
        },
        "balance_due": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The outstanding amount that remains to be paid on this invoice. May be labeled as 'Balance Due', 'Amount Due', or similar. In some documents, this may be the same as the total amount if no prior payments or credits have been applied.",
          "extend:type": "currency",
          "additionalProperties": False
        },
        "vendor_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name of the company or individual issuing the invoice. This is the party requesting payment, often found at the top or in a header section."
        },
        "invoice_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "The date when this invoice was created or issued. This is the official date for accounting and payment term calculations. May be labeled as 'Date', 'Invoice Date', or similar, and can appear in various formats.",
          "extend:type": "date"
        },
        "total_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The final amount owed by the customer, including all items, taxes, and adjustments. This is the complete payment obligation. May be labeled as 'Total', 'Amount Due', 'Balance Due', or similar, and is often the most prominent monetary value on the document.",
          "extend:type": "currency",
          "additionalProperties": False
        },
        "invoice_number": {
          "type": [
            "string",
            "null"
          ],
          "description": "The unique identifier assigned to this invoice or billing document. This is the primary reference number for the transaction and may include numbers, letters, or special characters. Common labels include 'Invoice #', 'Bill Number', or may appear as a prominent number near the top or center of the document."
        },
        "subtotal_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The sum of all line item amounts before taxes, discounts, or additional charges. May be labeled as 'Subtotal' or similar. Represents the total of goods and services prior to adjustments.",
          "extend:type": "currency",
          "additionalProperties": False
        }
      },
      "additionalProperties": False
    },
    "advancedOptions": {
      "citationsEnabled": True,
      "chunkingOptions": {},
      "advancedFigureParsingEnabled": True
    }
  }
```

**`Invoice Sample config (Python)`**

```json Invoice Sample config (Python)
"config": {
    "type": "EXTRACT",
    "baseProcessor": "extraction_performance",
    "baseVersion": "4.1.1",
    "schema": {
      "type": "object",
      "required": [
        "bill_to",
        "ship_to",
        "due_date",
        "line_items",
        "tax_amount",
        "balance_due",
        "vendor_name",
        "invoice_date",
        "total_amount",
        "invoice_number",
        "subtotal_amount"
      ],
      "properties": {
        "bill_to": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name and address of the individual or organization being billed. This is the recipient of the invoice and payment request. May appear under labels such as 'Bill To', 'Billed To', or similar."
        },
        "ship_to": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name and address where goods or services are to be delivered, if different from the billing address. May be labeled as 'Ship To', 'Shipping Address', or similar."
        },
        "due_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "The date by which payment for this invoice is expected. May be explicitly labeled as 'Due Date', 'Payment Due', or may require calculation based on payment terms. The key is identifying when the payment obligation becomes due.",
          "extend:type": "date"
        },
        "line_items": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "amount",
              "quantity",
              "unit_price",
              "description"
            ],
            "properties": {
              "amount": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The total cost for this line item, typically calculated as quantity multiplied by unit price. May also be labeled as 'Amount', 'Line Total', or similar."
              },
              "quantity": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The number of units, items, or hours billed for this line item. Can be a whole number or decimal."
              },
              "unit_price": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The price per single unit of this item before quantity multiplication. Represents the base rate for one unit."
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A description of the product or service provided in this line item. May include item names, service details, or product codes."
              }
            },
            "additionalProperties": False
          },
          "description": "The individual products, services, or charges that make up this invoice. Each item typically includes a description, quantity, unit price, and total amount. Format may vary from tables to lists."
        },
        "tax_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The total tax applied to this invoice. May be labeled as 'Tax', 'Sales Tax', or include a percentage. Represents the sum of all taxes charged.",
          "extend:type": "currency",
          "additionalProperties": False
        },
        "balance_due": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The outstanding amount that remains to be paid on this invoice. May be labeled as 'Balance Due', 'Amount Due', or similar. In some documents, this may be the same as the total amount if no prior payments or credits have been applied.",
          "extend:type": "currency",
          "additionalProperties": False
        },
        "vendor_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name of the company or individual issuing the invoice. This is the party requesting payment, often found at the top or in a header section."
        },
        "invoice_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "The date when this invoice was created or issued. This is the official date for accounting and payment term calculations. May be labeled as 'Date', 'Invoice Date', or similar, and can appear in various formats.",
          "extend:type": "date"
        },
        "total_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The final amount owed by the customer, including all items, taxes, and adjustments. This is the complete payment obligation. May be labeled as 'Total', 'Amount Due', 'Balance Due', or similar, and is often the most prominent monetary value on the document.",
          "extend:type": "currency",
          "additionalProperties": False
        },
        "invoice_number": {
          "type": [
            "string",
            "null"
          ],
          "description": "The unique identifier assigned to this invoice or billing document. This is the primary reference number for the transaction and may include numbers, letters, or special characters. Common labels include 'Invoice #', 'Bill Number', or may appear as a prominent number near the top or center of the document."
        },
        "subtotal_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The sum of all line item amounts before taxes, discounts, or additional charges. May be labeled as 'Subtotal' or similar. Represents the total of goods and services prior to adjustments.",
          "extend:type": "currency",
          "additionalProperties": False
        }
      },
      "additionalProperties": False
    },
    "advancedOptions": {
      "citationsEnabled": True,
      "chunkingOptions": {},
      "advancedFigureParsingEnabled": True
    }
  }
```

**`Invoice Sample config (Java SDK)`**

```java Invoice Sample config (Java SDK)
"config": {
    "type": "EXTRACT",
    "baseProcessor": "extraction_performance",
    "baseVersion": "4.1.1",
    "schema": {
      "type": "object",
      "required": [
        "bill_to",
        "ship_to",
        "due_date",
        "line_items",
        "tax_amount",
        "balance_due",
        "vendor_name",
        "invoice_date",
        "total_amount",
        "invoice_number",
        "subtotal_amount"
      ],
      "properties": {
        "bill_to": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name and address of the individual or organization being billed. This is the recipient of the invoice and payment request. May appear under labels such as 'Bill To', 'Billed To', or similar."
        },
        "ship_to": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name and address where goods or services are to be delivered, if different from the billing address. May be labeled as 'Ship To', 'Shipping Address', or similar."
        },
        "due_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "The date by which payment for this invoice is expected. May be explicitly labeled as 'Due Date', 'Payment Due', or may require calculation based on payment terms. The key is identifying when the payment obligation becomes due.",
          "extend:type": "date"
        },
        "line_items": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "amount",
              "quantity",
              "unit_price",
              "description"
            ],
            "properties": {
              "amount": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The total cost for this line item, typically calculated as quantity multiplied by unit price. May also be labeled as 'Amount', 'Line Total', or similar."
              },
              "quantity": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The number of units, items, or hours billed for this line item. Can be a whole number or decimal."
              },
              "unit_price": {
                "type": [
                  "number",
                  "null"
                ],
                "description": "The price per single unit of this item before quantity multiplication. Represents the base rate for one unit."
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A description of the product or service provided in this line item. May include item names, service details, or product codes."
              }
            },
            "additionalProperties": false
          },
          "description": "The individual products, services, or charges that make up this invoice. Each item typically includes a description, quantity, unit price, and total amount. Format may vary from tables to lists."
        },
        "tax_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The total tax applied to this invoice. May be labeled as 'Tax', 'Sales Tax', or include a percentage. Represents the sum of all taxes charged.",
          "extend:type": "currency",
          "additionalProperties": false
        },
        "balance_due": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The outstanding amount that remains to be paid on this invoice. May be labeled as 'Balance Due', 'Amount Due', or similar. In some documents, this may be the same as the total amount if no prior payments or credits have been applied.",
          "extend:type": "currency",
          "additionalProperties": false
        },
        "vendor_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The name of the company or individual issuing the invoice. This is the party requesting payment, often found at the top or in a header section."
        },
        "invoice_date": {
          "type": [
            "string",
            "null"
          ],
          "description": "The date when this invoice was created or issued. This is the official date for accounting and payment term calculations. May be labeled as 'Date', 'Invoice Date', or similar, and can appear in various formats.",
          "extend:type": "date"
        },
        "total_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The final amount owed by the customer, including all items, taxes, and adjustments. This is the complete payment obligation. May be labeled as 'Total', 'Amount Due', 'Balance Due', or similar, and is often the most prominent monetary value on the document.",
          "extend:type": "currency",
          "additionalProperties": false
        },
        "invoice_number": {
          "type": [
            "string",
            "null"
          ],
          "description": "The unique identifier assigned to this invoice or billing document. This is the primary reference number for the transaction and may include numbers, letters, or special characters. Common labels include 'Invoice #', 'Bill Number', or may appear as a prominent number near the top or center of the document."
        },
        "subtotal_amount": {
          "type": "object",
          "required": [
            "amount",
            "iso_4217_currency_code"
          ],
          "properties": {
            "amount": {
              "type": [
                "number",
                "null"
              ]
            },
            "iso_4217_currency_code": {
              "type": [
                "string",
                "null"
              ]
            }
          },
          "description": "The sum of all line item amounts before taxes, discounts, or additional charges. May be labeled as 'Subtotal' or similar. Represents the total of goods and services prior to adjustments.",
          "extend:type": "currency",
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "advancedOptions": {
      "citationsEnabled": true,
      "chunkingOptions": {},
      "advancedFigureParsingEnabled": true
    }
  }
```

## Step 3: Upload Your File

If you do not have a file URL for your document already, and are not following along with the sample invoice document, you can upload your document into Extend using the upload file endpoint. We will return to you a `fileId` which you can then use to process your document.

**`TypeScript SDK`**

```typescript TypeScript SDK
import { ExtendClient } from "extend-ai";
import * as fs from "fs";
const client = new ExtendClient({ token: "YOUR_TOKEN" });
const result = await client.file.upload(fs.createReadStream("/path/to/your/file"));
console.log(result);
```

**`TypeScript`**

```typescript TypeScript
import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("./path/to/your-file.pdf")]), "your-file.pdf");

const res = await fetch("https://api.extend.ai/files/upload", {
  method: "POST",
  headers: {
    Authorization: "Bearer <YOUR_API_KEY>",
    "x-extend-api-version": "2025-04-21",
  },
  body: form,
});

const data = await res.json();
console.log(data);
```

**`Python SDK`**

```python Python SDK
from extend_ai import Extend

client = Extend(token="YOUR_TOKEN")

# Provide a local file path
with open("/path/to/your/file.pdf", "rb") as f:
    response = client.file.upload(file=f)

print(response)
```

**`Python`**

```python Python
import requests

with open("./path/to/your-file.pdf", "rb") as f:
    files = {"file": f}
    res = requests.post(
        "https://api.extend.ai/files/upload",
        headers={
            "Authorization": "Bearer <YOUR_API_KEY>",
            "x-extend-api-version": "2025-04-21",
        },
        files=files,
    )
    print(res.json())
```

**`Java SDK`**

```java Java SDK
import ai.extend.ExtendClient;

ExtendClient client = new ExtendClient("<YOUR_API_KEY>");

java.io.File file = Paths.get("/path/to/your/file.pdf").toFile();
FileUploadResponse upload = client.file().upload(file, FileUploadRequest.builder().build());

System.out.println("File upload: " + upload);
```

**`cURL`**

```bash cURL
curl -X POST \
  "https://api.extend.ai/files/upload" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "x-extend-api-version: 2025-04-21" \
  -F "file=@./path/to/your-file.pdf"
```

## Step 4: Run Processor and Get Results

Now we will run our Extractor against our document, using the code snippet from step 2.

If you have a URL for your file, or are following along with our sample invoice document, you should replace `YOUR_FILE_URL` with that URL, and delete the `YOUR_FILE_ID` option.

If you uploaded a file into Extend with the upload file endpoint, you should replace `YOUR_FILE_ID` with the id returned from that endpoint, and delete the `YOUR_FILE_URL` section.

Also, be sure to replace `YOUR_API_KEY_HERE` and `YOUR_PROCESSOR_ID` with the appropriate values.

Execute the code in your environment. You should see the extracted data in your console! To interpret the response structure, see [Extractor output type](/2025-04-21/product/extraction/output-types).

See the below snippets which put everything together (uploading the file and running the Extractor).

**`TypeScript SDK`**

```typescript TypeScript SDK
import { ExtendClient } from "extend-ai";
import * as fs from "fs";

const client = new ExtendClient({ token: "YOUR_API_KEY" });

// Upload the file
const upload = await client.file.upload(fs.createReadStream("/path/to/your/file.pdf"));
const fileId = upload.file.id;

// Run the extractor
const response = await client.processorRun.create({
  processorId: "<YOUR_PROCESSOR_ID>",
  file: { fileId },
  sync: true,
  config: {
    // Put your config here, or copy our sample invoice config above
  }
});

console.log("Processor run:", response);
```

**`TypeScript`**

```typescript TypeScript
import fs from "node:fs";

// Upload the file
const form = new FormData();
form.append("file", new Blob([fs.readFileSync("./path/to/your-file.pdf")]), "your-file.pdf");

const uploadRes = await fetch("https://api.extend.ai/files/upload", {
  method: "POST",
  headers: {
    Authorization: "Bearer <YOUR_API_KEY>",
    "x-extend-api-version": "2025-04-21",
  },
  body: form,
});

const uploadData = await uploadRes.json();
const fileId = uploadData.file.id;

// Run the extractor
const runRes = await fetch("https://api.extend.ai/processor_runs", {
  method: "POST",
  headers: {
    "x-extend-api-version": "2025-04-21",
    Authorization: "Bearer <YOUR_API_KEY>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    processorId: "<YOUR_PROCESSOR_ID>",
    file: { fileId },
    sync: true,
    config: {
      // Put your config here, or copy our sample invoice config above
    },
  }),
});

const runData = await runRes.json();
console.log(runData);
```

**`Python SDK`**

```python Python SDK
from extend_ai import Extend

client = Extend(token="YOUR_API_KEY")

# Upload the file
with open("/path/to/your/file.pdf", "rb") as f:
    upload_response = client.file.upload(file=f)

# Extract the file ID from the upload response
file_id = upload_response.file.id

# Run the extractor
response = client.processor_run.create(
    processor_id="<YOUR_PROCESSOR_ID>",
    file={"fileId": file_id},
    sync=True,
    config={
        # Put your config here, or copy our sample invoice config above
    },
)

print(response)
```

**`Python`**

```python Python
import requests

# Upload the file
with open("./path/to/your-file.pdf", "rb") as f:
    files = {"file": f}
    upload_res = requests.post(
        "https://api.extend.ai/files/upload",
        headers={
            "Authorization": "Bearer <YOUR_API_KEY>",
            "x-extend-api-version": "2025-04-21",
        },
        files=files,
    )
    file_id = upload_res.json()["file"]["id"]

# Run the extractor
run_res = requests.post(
    "https://api.extend.ai/processor_runs",
    json={
        "processorId": "<YOUR_PROCESSOR_ID>",
        "file": {"fileId": file_id},
        "sync": True,
        "config": {
            # Put your config here, or copy our sample invoice config above
        },
    },
    headers={
        "x-extend-api-version": "2025-04-21",
        "Authorization": "Bearer <YOUR_API_KEY>",
        "Content-Type": "application/json",
    },
)

print(run_res.json())
```

**`Java SDK`**

```java Java SDK
import ai.extend.ExtendClient;

ExtendClient client = new ExtendClient("<YOUR_API_KEY>");

java.io.File file = Paths.get("/path/to/your/file.pdf").toFile();
FileUploadResponse upload = client.file().upload(file, FileUploadRequest.builder().build());
String fileId = upload.getFile().getId();

ProcessorRunCreateRequest runReq = ProcessorRunCreateRequest.builder()
    .processorId("<YOUR_PROCESSOR_ID>")
    .file(ProcessorRunFileInput.builder()
        .fileId(fileId)
        .build())
    .build();
ProcessorRunCreateResponse run = client.processorRun().create(runReq);
String processorRunId = run.getProcessorRun().getId();

System.out.println("File upload: " + upload);
```

## Next steps

* **How can I view the API endpoint to run an extractor?**
  * Review the [Run Processor endpoint](/2025-04-21/developers/api-reference/processor-endpoints/run-processor) for full request/response details.
* **How can I configure my extraction schema?**
  * See the [JSON Schema guide](/2025-04-21/product/extraction/schema).
* **How can I set up webhooks?**
  * Follow [Webhooks configuration](/2025-04-21/product/webhooks/configuration) to receive asynchronous run-completion events and results.
* **When should I use the `sync: true` flag?**
  * For this quick evaluation, we recommend `sync: true` for immediate results.
  * For production, use `sync: true` only when latency is predictable and under 5 minutes and documents are small. Otherwise, run asynchronously and rely on [webhooks](/2025-04-21/product/webhooks/configuration).
* **How can I assess the accuracy of Extend?**
  * Use [Evaluation Sets](/2025-04-21/product/evaluation/overview) to measure performance on your own ground truth. Create a set, run your extractor across it, and review diffs and accuracy metrics.