Run Workflow

POST

https://api-prod.extend.app/workflow_runs

POST

/workflow_runs

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

Try it

200

1 {
2   "success": true,
3   "workflowRuns": [
4     {
5       "object": "workflow_run",
6       "id": "workflow_run_xKm9pNv3qWsY_jL2tR5Dh",
7       "name": "myFirstFile.pdf",
8       "url": "https://dashboard.extend.app/workflows/workflow_Bk9mNp2qWs5_xL8vR4tYh?workflowRunId=workflow_run_Zj3nMx7ZPd9f4c2WQ_kAg",
9       "status": "PENDING",
10       "metadata": {},
11       "files": [
12         {
13           "object": "file",
14           "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
15           "name": "Invoices.pdf",
16           "type": "PDF",
17           "metadata": {
18             "pageCount": 30,
19             "parentSplit": {
20               "id": "foo",
21               "type": "Invoice",
22               "identifier": "other_2_9",
23               "startPage": 1,
24               "endPage": 10
25             }
26           },
27           "createdAt": "2024-03-21T15:30:00Z",
28           "updatedAt": "2024-03-21T16:45:00Z",
29           "presignedUrl": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
30           "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
31           "contents": {
32             "rawText": "foo",
33             "markdown": "foo",
34             "pages": [
35               {
36                 "pageNumber": 1,
37                 "pageHeight": 10,
38                 "pageWidth": 10,
39                 "rawText": "This is the raw text of the page.",
40                 "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",
41                 "html": "<div>This is the html of the page.</div>"
42               }
43             ],
44             "sheets": [
45               {
46                 "sheetName": "Sheet1",
47                 "rawText": "This is the raw text of the sheet."
48               }
49             ]
50           }
51         }
52       ],
53       "initialRunAt": "2025-04-28T17:01:39.285Z",
54       "reviewed": true,
55       "outputs": [
56         {
57           "object": "document_processor_run",
58           "id": "dpr_Xj8mK2pL9nR4vT7qY5wZ",
59           "processorId": "dp_Xj8mK2pL9nR4vT7qY5wZ",
60           "processorVersionId": "dpv_Xj8mK2pL9nR4vT7qY5wZ",
61           "processorName": "Invoice Processor",
62           "status": "PROCESSING",
63           "reviewed": false,
64           "edited": false,
65           "edits": {
66             "originalValue": null,
67             "editedValue": null,
68             "notes": "This is a note about the edit.",
69             "page": 15,
70             "fieldType": "string"
71           },
72           "type": "EXTRACT",
73           "config": {
74             "type": "CLASSIFY",
75             "baseProcessor": "classifier_performance",
76             "baseVersion": "3.2.0",
77             "classifications": [
78               {
79                 "id": "my_unique_id",
80                 "type": "invoice",
81                 "description": "An invoice is a document that lists the items purchased and the total amount due."
82               }
83             ],
84             "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.",
85             "advancedOptions": {
86               "context": "default",
87               "advancedMultimodalEnabled": false,
88               "fixedPageLimit": 10
89             }
90           },
91           "output": {
92             "value": {},
93             "metadata": {}
94           },
95           "files": [
96             {
97               "object": "file",
98               "id": "file_xK9mLPqRtN3vS8wF5hB2cQ",
99               "name": "Invoices.pdf",
100               "type": "PDF",
101               "metadata": {
102                 "pageCount": 30,
103                 "parentSplit": {
104                   "id": "foo",
105                   "type": "Invoice",
106                   "identifier": "other_2_9",
107                   "startPage": 1,
108                   "endPage": 10
109                 }
110               },
111               "createdAt": "2024-03-21T15:30:00Z",
112               "updatedAt": "2024-03-21T16:45:00Z",
113               "presignedUrl": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
114               "parentFileId": "file_Zk9mNP12Qw4yTv8BdR3H",
115               "contents": {
116                 "rawText": "foo",
117                 "markdown": "foo",
118                 "pages": [
119                   {
120                     "pageNumber": 1,
121                     "pageHeight": 10,
122                     "pageWidth": 10,
123                     "rawText": "This is the raw text of the page.",
124                     "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",
125                     "html": "<div>This is the html of the page.</div>"
126                   }
127                 ],
128                 "sheets": [
129                   {
130                     "sheetName": "Sheet1",
131                     "rawText": "This is the raw text of the sheet."
132                   }
133                 ]
134               }
135             }
136           ],
137           "mergedProcessors": [
138             {
139               "processorId": "dp_Xj8mK2pL9nR4vT7qY5wZ",
140               "processorVersionId": "dpv_Xj8mK2pL9nR4vT7qY5wZ",
141               "processorName": "Invoice Line Items Processor"
142             }
143           ],
144           "url": "https://app.extend.app/runs/dpr_Xj8mK2pL9nR4vT7qY5wZ",
145           "failureReason": "foo",
146           "failureMessage": "foo",
147           "metadata": {},
148           "initialOutput": {
149             "value": {},
150             "metadata": {}
151           },
152           "reviewedOutput": {
153             "value": {},
154             "metadata": {}
155           }
156         }
157       ],
158       "stepRuns": [
159         {
160           "object": "workflow_step_run",
161           "id": "workflow_step_run_xKm9pNv3qWsY_jL2tR5Dh",
162           "status": "PENDING",
163           "step": {
164             "object": "workflow_step",
165             "id": "step_xKm9pNv3qWsY_jL2tR5Dh",
166             "name": "Validate Invoice Total",
167             "type": "EXTERNAL_DATA_VALIDATION"
168           },
169           "output": {
170             "rules": [
171               {
172                 "name": "foo",
173                 "valid": true,
174                 "validArray": [
175                   "foo"
176                 ],
177                 "failureReason": "RULE_FAILED",
178                 "error": "foo"
179               }
180             ]
181           }
182         }
183       ],
184       "workflow": {
185         "object": "workflow",
186         "id": "workflow_BMlfq_yWM3sT-ZzvCnA3f",
187         "version": "draft",
188         "name": "Invoice Processing"
189       },
190       "batchId": "batch_7Ws31-F5",
191       "failureReason": "foo",
192       "failureMessage": "foo",
193       "reviewedBy": "jane.doe@example.com",
194       "rejectionNote": "foo",
195       "reviewedAt": "2024-03-21T16:45:00Z",
196       "startTime": "2024-03-21T15:30:00Z",
197       "endTime": "2024-03-21T15:35:00Z"
198     }
199   ]
200 }

Run a Workflow with files. A Workflow is a sequence of steps that process files and data in a specific order to achieve a desired outcome. A WorkflowRun will be created for each file processed. A WorkflowRun represents a single execution of a workflow against a file.

Request

This endpoint expects an object.

workflowIdstringRequired

The ID of the workflow to run. The ID will start with “workflow”. This ID can be found viewing the workflow on the Extend platform.

Example: "workflow_BMdfq_yWM3sT-ZzvCnA3f"

fileslist of objectsOptional

An array of files to process through the workflow. Either the files array or rawTexts array must be provided. Supported file types can be found here.

rawTextslist of stringsOptional

An array of raw strings. Can be used in place of files when passing raw data. The raw data will be converted to .txt files and run through the workflow. If the data follows a specific format, it is recommended to use the files parameter instead. Either files or rawTexts must be provided.

versionstringOptional

An optional version of the workflow that files will be run through. This number can be found when viewing the workflow on the Extend platform. When a version number is not supplied, the most recent published version of the workflow will be used. If no published versions exist, the draft version will be used. To run the "draft" version of a workflow, use "draft" as the version.

Examples:

"3" - Run version 3 of the workflow
"draft" - Run the draft version of the workflow

priorityintegerOptional>=1<=100Defaults to 50

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

metadataobjectOptional

A optional metadata object that can be assigned to a specific WorkflowRun to help identify it. It will be returned in the response and webhooks. You can place any arbitrary key : value pairs in this object.

Response

Successfully created workflow runs

successboolean

workflowRunslist of objects

An array of WorkflowRun objects, with each WorkflowRun corresponding to a single File that was passed in.

Run Workflow

Headers

Request

Response

Errors