Run Processor

curl --location --request POST 'https://api-prod.extend.app/v1/processor_runs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
    "processorId": "dp_1234",
    "file": {
        "fileName": "example.pdf",
        "fileUrl": "https://test.s3.amazonaws.com/example.pdf"
    },
    "version": "1.0",
    "priority": 50,
    "metadata": {
        "internal_id": "id_1234"
    }
}'

const axios = require("axios");

const runProcessor = async () => {
  try {
    const response = await axios.post(
      "https://api-prod.extend.app/v1/processor_runs",
      {
        processorId: "dp_1234",
        file: {
          fileName: "example.pdf",
          fileUrl: "https://test.s3.amazonaws.com/example.pdf",
        },
        version: "1.0",
        priority: 50,
        metadata: {
          internal_id: "id_1234",
        },
      },
      {
        headers: {
          Authorization: "Bearer <API_TOKEN>",
          "Content-Type": "application/json",
        },
      }
    );

    console.log("Processor run created:", response.data);
  } catch (error) {
    console.error("Error:", error.response?.data || error.message);
  }
};

runProcessor();

import requests

url = "https://api-prod.extend.app/v1/processor_runs"
headers = {
    "Authorization": "Bearer <API_TOKEN>",
    "Content-Type": "application/json"
}
payload = {
    "processorId": "dp_1234",
    "file": {
        "fileName": "example.pdf",
        "fileUrl": "https://test.s3.amazonaws.com/example.pdf"
    },
    "version": "1.0",
    "priority": 50,
    "metadata": {
        "internal_id": "id_1234"
    }
}

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    print("Processor run created:", response.json())
except requests.exceptions.RequestException as e:
    print("Error:", e)

{
  "success": true,
  "processorRun": {
    "object": "document_processor_run",
    "id": "dpr_1234",
    "output": null, // Will be null until the run is processed
    "processorId": "dp_5678",
    "processorVersionId": "dpv_91011",
    "processorName": "Invoice Extractor",
    "status": "PROCESSING",
    "metadata": {
      "internal_id": "id_1234"
    },
    "reviewed": false,
    "edited": false,
    "edits": null,
    "type": "EXTRACT",
    "config": {
      "fields": [
        {
          "id": "total_amount",
          "name": "Total Amount",
          "type": "currency"
        }
      ]
    },
    "files": [
      {
        "name": "example.pdf"
      }
    ],
    "url": "https://dashboard.extend.app/runs/dpr_1234"
  }
}

curl --location --request POST 'https://api-prod.extend.app/v1/processor_runs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
    "processorId": "dp_1234",
    "file": {
        "fileName": "example.pdf",
        "fileUrl": "https://test.s3.amazonaws.com/example.pdf"
    },
    "version": "1.0",
    "priority": 50,
    "metadata": {
        "internal_id": "id_1234"
    }
}'

const axios = require("axios");

const runProcessor = async () => {
  try {
    const response = await axios.post(
      "https://api-prod.extend.app/v1/processor_runs",
      {
        processorId: "dp_1234",
        file: {
          fileName: "example.pdf",
          fileUrl: "https://test.s3.amazonaws.com/example.pdf",
        },
        version: "1.0",
        priority: 50,
        metadata: {
          internal_id: "id_1234",
        },
      },
      {
        headers: {
          Authorization: "Bearer <API_TOKEN>",
          "Content-Type": "application/json",
        },
      }
    );

    console.log("Processor run created:", response.data);
  } catch (error) {
    console.error("Error:", error.response?.data || error.message);
  }
};

runProcessor();

import requests

url = "https://api-prod.extend.app/v1/processor_runs"
headers = {
    "Authorization": "Bearer <API_TOKEN>",
    "Content-Type": "application/json"
}
payload = {
    "processorId": "dp_1234",
    "file": {
        "fileName": "example.pdf",
        "fileUrl": "https://test.s3.amazonaws.com/example.pdf"
    },
    "version": "1.0",
    "priority": 50,
    "metadata": {
        "internal_id": "id_1234"
    }
}

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    print("Processor run created:", response.json())
except requests.exceptions.RequestException as e:
    print("Error:", e)

{
  "success": true,
  "processorRun": {
    "object": "document_processor_run",
    "id": "dpr_1234",
    "output": null, // Will be null until the run is processed
    "processorId": "dp_5678",
    "processorVersionId": "dpv_91011",
    "processorName": "Invoice Extractor",
    "status": "PROCESSING",
    "metadata": {
      "internal_id": "id_1234"
    },
    "reviewed": false,
    "edited": false,
    "edits": null,
    "type": "EXTRACT",
    "config": {
      "fields": [
        {
          "id": "total_amount",
          "name": "Total Amount",
          "type": "currency"
        }
      ]
    },
    "files": [
      {
        "name": "example.pdf"
      }
    ],
    "url": "https://dashboard.extend.app/runs/dpr_1234"
  }
}

In general, the recommended way to integrate with Extend in production is via workflows, using the Run Workflow endpoint. This is due to several factors:

file parsing/pre-processing will automatically be reused across multiple processors, which will give you simplicity and cost savings given that many use cases will require multiple processors to be run on the same document.
workflows provide dedicated human in the loop document review, when needed.
workflows allow you to model and manage your pipeline with a single endpoint and corresponding UI for modeling and monitoring.

However, there are a number of legitimate use cases and systems where it might be easier to model the pipeline via code and run processors directly. This endpoint is provided for this purpose. Similar to workflow runs, processor runs are asynchronous and will return a status of PROCESSING until the run is complete. You can configure webhooks to receive notifications when a processor run is complete or failed.

Body

string

required

The ID of the processor that will process the input. This ID can be fetched from viewing the processor on the Extend platform.

object

A file object containing either a URL or base64 encoded content. Must contain either fileUrl or fileBase64. Presigned URLs are recommended for most production use cases. Supported file types can be found here.

Hide properties

string

required

The name of the file.

string

A presigned URL for the file. Though we will download immediately, we recommend a 5 - 15 minute expiration time.

string

deprecated

Base64 encoded content of the file. Can be used instead of fileUrl in development environments.DEPRECATED: This field is deprecated and will be removed in a future release. Use the /upload endpoint instead.

string

If you already have an Extend file id (for instance from running a parser or a previous file creation) then you can run a processor via file id, and any parsed data will be reused.

string

A raw string to be processed. Can be used in place of file when passing raw text data streams. Either file or rawText must be provided.

string

default:"latest"

An optional version of the processor to use. When not supplied, the most recent published version of the processor will be used. Special values include: - “latest” for the most recent published version (the default). If no published versions, the draft version will be used. - “draft” for the draft version. - Specific version numbers corresponding to versions your team has published, e.g. “1.0”, “2.2”, etc.

number

default:"50"

An optional value used to determine the relative order of processor runs when rate limiting is in effect. Priority values must be an integer between 1 and 100 inclusive. Lower values will be prioritized before higher values. The default priority value is 50.

object

An optional object that can be passed in to identify the processor run in your systems. It will be returned in the response and webhooks.

object

An option to override the config of the processor.

Extraction
Classification
Splitter

Show properties

string

required

Must be "EXTRACT" for extraction processors.

string

The base processor to use. For extractors, this is either "extraction_performance" or "extraction_light". See the base processor documentation for more details.

string

The version of the base processor to use (e.g. "4.0.0"). If this is provided, baseProcessor must be provided as well. See the processor changelog for available versions.

object

The schema that defines the structure of data to extract from documents. One of schema or fields must be provided. We recommend using schema as fields is deprecated. See the extraction processor schema documentation for more details.

array

deprecated

Show properties

string

required

Unique identifier for the field.

string

required

Human-readable name for the field.

string

required

Type of the field. Supported values:

string: Text values
number: Numeric values
currency: Monetary values
boolean: True/false values
date: Date values
array: Lists of values (requires schema)
enum: Values from a predefined list (requires enum)
object: Nested structure (requires schema)
signature: Signature information

string

required

Detailed description of the field, including expected content and format.

array

Required when type is “array” or “object”. Contains nested field definitions.

array

Required when type is “enum”. List of allowed values.

Show properties

string

required

The enum value.

string

required

Description of the enum value.

string

Custom rules to guide the extraction process in natural language.

object

Advanced configuration options.

Show properties

number

Limit processing to a specific number of pages from the beginning of the document.

string

Provide a hint about the document type (e.g. “invoice”, “receipt”, etc.).

string

Define specific key terms or concepts relevant to the document type.

boolean

Enable model reasoning insights in the extraction results.

boolean

Enable advanced multimodal processing for better handling of visual elements.

boolean

Enable citation information for extracted fields.

boolean

Enable advanced parsing of figures and diagrams in the document.

object

Options for controlling document chunking.

Show properties

string

Strategy for chunking the document. Supported values:

standard: Default chunking strategy
semantic: Content-aware chunking based on document structure

string

Custom rules for semantic chunking in natural language.

number

Number of pages per chunk.

string

Strategy for selecting chunks. Supported values:

intelligent: AI-based selection
confidence: Select based on confidence score
take_first: Always use first chunk
take_last: Always use last chunk

Show properties

string

required

Must be "CLASSIFY" for classification processors.

string

The base processor to use. For classifiers, must be "classification_performance" or "classification_light". See the base processor documentation for more details.

string

The version of the base processor to use (e.g. "3.2.0"). If this is provided, baseProcessor must be provided as well. See the processor changelog for available versions.

array

required

Array of possible classifications for the document.

Show properties

string

required

Unique identifier for the classification. We recommend lowercase, underscore-separated format.

string

required

Type identifier for the classification.

string

required

Detailed description of the classification.

string

Custom rules to guide the classification process in natural language.

object

Advanced configuration options.

Show properties

number

Limit processing to a specific number of pages from the beginning of the document.

string

The context to use for classification. Supported values: default max

boolean

Enable advanced multimodal processing for better handling of visual elements during classification.

Show properties

string

required

Must be "SPLITTER" for splitter processors.

string

The base processor to use. For splitters, this can currently only be "splitter_performance". See the base processor documentation for more details.

string

The version of the base processor to use (e.g. "1.0.0"). If this is provided, baseProcessor must be provided as well. See the processor changelog for available versions.

array

required

Array of classifications that define the possible types of document sections.

Show properties

string

required

Unique identifier for the split classification.

string

required

Type identifier for the split classification.

string

required

Detailed description of the document section type.

string

Custom rules to guide the document splitting process in natural language.

object

Advanced configuration options.

Show properties

number

Limit processing to a specific number of pages from the beginning of the document.

string

Method to use for splitting. Supported values:

high_precision: More accurate but potentially slower
low_latency: Faster but potentially less precise

string

boolean

For Excel documents, split by worksheet.

curl --location --request POST 'https://api-prod.extend.app/v1/processor_runs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
    "processorId": "dp_1234",
    "file": {
        "fileName": "example.pdf",
        "fileUrl": "https://test.s3.amazonaws.com/example.pdf"
    },
    "version": "1.0",
    "priority": 50,
    "metadata": {
        "internal_id": "id_1234"
    }
}'

const axios = require("axios");

const runProcessor = async () => {
  try {
    const response = await axios.post(
      "https://api-prod.extend.app/v1/processor_runs",
      {
        processorId: "dp_1234",
        file: {
          fileName: "example.pdf",
          fileUrl: "https://test.s3.amazonaws.com/example.pdf",
        },
        version: "1.0",
        priority: 50,
        metadata: {
          internal_id: "id_1234",
        },
      },
      {
        headers: {
          Authorization: "Bearer <API_TOKEN>",
          "Content-Type": "application/json",
        },
      }
    );

    console.log("Processor run created:", response.data);
  } catch (error) {
    console.error("Error:", error.response?.data || error.message);
  }
};

runProcessor();

import requests

url = "https://api-prod.extend.app/v1/processor_runs"
headers = {
    "Authorization": "Bearer <API_TOKEN>",
    "Content-Type": "application/json"
}
payload = {
    "processorId": "dp_1234",
    "file": {
        "fileName": "example.pdf",
        "fileUrl": "https://test.s3.amazonaws.com/example.pdf"
    },
    "version": "1.0",
    "priority": 50,
    "metadata": {
        "internal_id": "id_1234"
    }
}

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    print("Processor run created:", response.json())
except requests.exceptions.RequestException as e:
    print("Error:", e)

Response

boolean

A true or false value indicating whether the processor run was created successfully.

object

Details about the created processor run.See the ProcessorRun object for more details.

Common errors

Returned when: - Required fields are missing (e.g., processorId) - Neither file nor rawText is provided - Invalid files: - The provided fileUrl is invalid - The provided fileBase64 is invalid - It’s an unsupported file type

The file is corrupted or otherwise cannot be downloaded - The priority value is outside the allowed range (must be between 1 and 100)

Returned when: - The specified processor ID doesn’t exist - The specified processor version doesn’t exist

Returned when: - The API token is missing - The API token is invalid

Returned when: - The authenticated workspace doesn’t have permission to access the specified processor - The API token doesn’t have sufficient permissions

{
  "success": true,
  "processorRun": {
    "object": "document_processor_run",
    "id": "dpr_1234",
    "output": null, // Will be null until the run is processed
    "processorId": "dp_5678",
    "processorVersionId": "dpv_91011",
    "processorName": "Invoice Extractor",
    "status": "PROCESSING",
    "metadata": {
      "internal_id": "id_1234"
    },
    "reviewed": false,
    "edited": false,
    "edits": null,
    "type": "EXTRACT",
    "config": {
      "fields": [
        {
          "id": "total_amount",
          "name": "Total Amount",
          "type": "currency"
        }
      ]
    },
    "files": [
      {
        "name": "example.pdf"
      }
    ],
    "url": "https://dashboard.extend.app/runs/dpr_1234"
  }
}

API Documentation

Workflow Endpoints

Processor Endpoints

Parse Endpoints

File Endpoints

Evaluation Set Endpoints

Objects

Guides

Webhooks

Body

Response

Common errors

​Body

​Response

​Common errors

Body

Response

Common errors