Skip to main content
POST
/
v2
/
flows
/
{id}
/
run
curl --request POST \
  --url https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form 'purchase_order=@/path/to/po.pdf' \
  --form 'invoice=@/path/to/invoice.pdf' \
  --form 'name=PO-123 Reconciliation' \
  --form 'purchase_order_metadata={"po_number": "PO-123"}' \
  --form 'purchase_order_guidance=The PO number may include revision info like REV:0 at the end — strip that and only extract the base PO number' \
  --form 'metadata={"customer_id": "12345"}'

{
  "id": "Wp7kRnT2mX4vQ9bL",
  "flow_id": "dk4g1tUg1uHLs8YU",
  "workspace_id": "uT2bJNWN75YPU95r",
  "status": "processing",
  "status_history": [
    {
      "status": "processing",
      "time": 1682366228,
      "message": "Flow started via api"
    }
  ],
  "error": null,
  "metadata": {
    "customer_id": "12345",
    "order_number": "PO-2024-001"
  },
  "trigger_method": "api",
  "start_time": 1682366228,
  "end_time": null,
  "duration": 0,
  "drive_files": {},
  "created_at": 1682366228,
  "updated_at": 1682366228
}
Executes a flow by uploading files and triggering the configured workflow steps.

​
Usage Notes

  • Files are uploaded as multipart/form-data
  • File field names must match the flow’s configuration
  • Required files must be provided or the request will fail
  • The flow executes asynchronously - use the returned ID to check status
  • Use metadata to include custom data that will be preserved in the flow run

​
Request

​
id
string
required
The ID of the flow to run
​
file
file
File(s) to upload. The field name must match the key defined in the flow’s file_input_config.file_fields. For fields that accept multiple files, append an index starting at 1 (e.g., attachments_1, attachments_2).
​
name
string
Optional name for the flow run. This is useful for identifying flow runs in the TableFlow UI.
​
{file_key}_metadata
string
JSON string containing metadata for a specific file. Replace {file_key} with the file field key (e.g., purchase_order_metadata). This metadata is associated with the individual file’s extraction.
​
{file_key}_guidance
string
Optional extraction guidance for a specific file. Replace {file_key} with the file field key (e.g., purchase_order_guidance). Use this to provide hints to the AI about the document structure or specific values to look for in that particular file.
​
metadata
string
JSON string containing metadata for the entire flow run. This metadata will be included in all flow run responses and webhooks.

​
Response

{
  "id": "Wp7kRnT2mX4vQ9bL",
  "flow_id": "dk4g1tUg1uHLs8YU",
  "workspace_id": "uT2bJNWN75YPU95r",
  "status": "processing",
  "status_history": [
    {
      "status": "processing",
      "time": 1682366228,
      "message": "Flow started via api"
    }
  ],
  "error": null,
  "metadata": {
    "customer_id": "12345",
    "order_number": "PO-2024-001"
  },
  "trigger_method": "api",
  "start_time": 1682366228,
  "end_time": null,
  "duration": 0,
  "drive_files": {},
  "created_at": 1682366228,
  "updated_at": 1682366228
}

curl --request POST \
  --url https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: multipart/form-data' \
  --form 'purchase_order=@/path/to/po.pdf' \
  --form 'invoice=@/path/to/invoice.pdf' \
  --form 'name=PO-123 Reconciliation' \
  --form 'purchase_order_metadata={"po_number": "PO-123"}' \
  --form 'purchase_order_guidance=The PO number may include revision info like REV:0 at the end — strip that and only extract the base PO number' \
  --form 'metadata={"customer_id": "12345"}'
​
id
string
required
The unique identifier for the flow run
​
flow_id
string
required
The ID of the flow being executed
​
workspace_id
string
required
The workspace ID
​
status
string
required
Current status of the flow run: processing, review, completed, or failed
​
status_history
array
required
History of status changes
​
error
string
Error message if the flow run failed
​
metadata
object
Custom metadata provided when running the flow
​
trigger_method
string
required
How the flow was triggered: api or manual
​
start_time
number
required
Unix timestamp when the flow run started
​
end_time
number
Unix timestamp when the flow run completed
​
duration
number
required
Duration of the flow run in milliseconds
​
created_at
number
required
Unix timestamp when the flow run was created
​
updated_at
number
required
Unix timestamp when the flow run was last updated