Run Processor

1 curl -X POST https://api-prod.extend.app/processor_runs \ 2 -H "x-extend-api-version: 2025-04-21" \ 3 -H "Authorization: Bearer <token>" \ 4 -H "Content-Type: application/json" \ 5 -d '{ 6 "processorId": "dp_Xj8mK2pL9nR4vT7qY5wZ" 7 }'

1 { 2 "success": true, 3 "processorRun": { 4 "object": "document_processor_run", 5 "id": "dpr_Xj8mK2pL9nR4vT7qY5wZ", 6 "processorId": "dp_Xj8mK2pL9nR4vT7qY5wZ", 7 "processorVersionId": "dpv_Xj8mK2pL9nR4vT7qY5wZ", 8 "processorName": "Invoice Processor", 9 "status": "PROCESSING", 10 "reviewed": false, 11 "edited": false, 12 "edits": { 13 "originalValue": null, 14 "editedValue": null, 15 "notes": "This is a note about the edit.", 16 "page": 15, 17 "fieldType": "string" 18 }, 19 "type": "EXTRACT", 20 "config": { 21 "type": "CLASSIFY", 22 "baseProcessor": "classifier_performance", 23 "baseVersion": "3.2.0", 24 "classifications": [ 25 { 26 "id": "my_unique_id", 27 "type": "invoice", 28 "description": "An invoice is a document that lists the items purchased and the total amount due." 29 } 30 ], 31 "classificationRules": "Rememeber, when it comes to differentiating between invoices and purchase orders, the most important thing to look for is the date of the document.", 32 "advancedOptions": { 33 "context": "default", 34 "advancedMultimodalEnabled": false, 35 "fixedPageLimit": 10 36 } 37 }, 38 "output": { 39 "value": {}, 40 "metadata": {} 41 }, 42 "files": [ 43 { 44 "object": "file", 45 "id": "file_xK9mLPqRtN3vS8wF5hB2cQ", 46 "name": "Invoices.pdf", 47 "type": "PDF", 48 "metadata": { 49 "pageCount": 30, 50 "parentSplit": { 51 "id": "foo", 52 "type": "Invoice", 53 "identifier": "other_2_9", 54 "startPage": 1, 55 "endPage": 10 56 } 57 }, 58 "createdAt": "2024-03-21T15:30:00Z", 59 "updatedAt": "2024-03-21T16:45:00Z", 60 "presignedUrl": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", 61 "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H", 62 "contents": { 63 "rawText": "foo", 64 "markdown": "foo", 65 "pages": [ 66 { 67 "pageNumber": 1, 68 "pageHeight": 10, 69 "pageWidth": 10, 70 "rawText": "This is the raw text of the page.", 71 "markdown": "# Heading\n\nThis is a paragraph with **bold** and *italic* text.\n\n- List item 1\n- List item 2\n\n> This is a blockquote", 72 "html": "<div>This is the html of the page.</div>" 73 } 74 ], 75 "sheets": [ 76 { 77 "sheetName": "Sheet1", 78 "rawText": "This is the raw text of the sheet." 79 } 80 ] 81 } 82 } 83 ], 84 "mergedProcessors": [ 85 { 86 "processorId": "dp_Xj8mK2pL9nR4vT7qY5wZ", 87 "processorVersionId": "dpv_Xj8mK2pL9nR4vT7qY5wZ", 88 "processorName": "Invoice Line Items Processor" 89 } 90 ], 91 "url": "https://app.extend.app/runs/dpr_Xj8mK2pL9nR4vT7qY5wZ", 92 "failureReason": "foo", 93 "failureMessage": "foo", 94 "metadata": {}, 95 "initialOutput": { 96 "value": {}, 97 "metadata": {} 98 }, 99 "reviewedOutput": { 100 "value": {}, 101 "metadata": {} 102 } 103 } 104 }

Run processors (extraction, classification, splitting, etc.) on a given document.

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.

Request

This endpoint expects an object.

processorIdstringRequired

The ID of the processor to be run. The id will start with "dp_". This ID can be found when viewing a processor on the Extend platform.

Example: "dp_Xj8mK2pL9nR4vT7qY5wZ"

versionstringOptionalDefaults to 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. If there are 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.

fileobjectOptional

The file to be processed. One of file or rawText must be provided. Supported file types can be found here.

rawTextstringOptional

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

priorityintegerOptional>=1<=100Defaults to 50

An optional value used to determine the relative order of ProcessorRuns when rate limiting is in effect. Lower values will be prioritized before higher values.

metadataobjectOptional

An optional object that can be passed in to identify the run of the document processor. It will be returned back to you in the response and webhooks.

configobjectOptional

The configuration for the processor run. If this is provided, this config will be used. If not provided, the config for the specific version you provide will be used. The type of configuration must match the processor type.

Response

Successfully created processor run

successboolean

processorRunobject

Run Processor

Headers

Request

Response

Errors