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"}'
import requests
import json
files = {
"purchase_order": open("po.pdf", "rb"),
"invoice": open("invoice.pdf", "rb")
}
data = {
"name": "PO-123 Reconciliation",
"purchase_order_metadata": json.dumps({"po_number": "PO-123"}),
"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",
"metadata": json.dumps({"customer_id": "12345"})
}
response = requests.post(
"https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run",
headers={
"Authorization": "Bearer YOUR_API_KEY"
},
files=files,
data=data
)
flow_run = response.json()
const formData = new FormData();
formData.append("purchase_order", purchaseOrderFile);
formData.append("invoice", invoiceFile);
formData.append("name", "PO-123 Reconciliation");
formData.append("purchase_order_metadata", JSON.stringify({ po_number: "PO-123" }));
formData.append("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");
formData.append("metadata", JSON.stringify({ customer_id: "12345" }));
const response = await fetch("https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY"
},
body: formData
});
const flowRun = await response.json();
{
"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
}
Flows
Run Flow
Execute a flow with uploaded files
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"}'
import requests
import json
files = {
"purchase_order": open("po.pdf", "rb"),
"invoice": open("invoice.pdf", "rb")
}
data = {
"name": "PO-123 Reconciliation",
"purchase_order_metadata": json.dumps({"po_number": "PO-123"}),
"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",
"metadata": json.dumps({"customer_id": "12345"})
}
response = requests.post(
"https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run",
headers={
"Authorization": "Bearer YOUR_API_KEY"
},
files=files,
data=data
)
flow_run = response.json()
const formData = new FormData();
formData.append("purchase_order", purchaseOrderFile);
formData.append("invoice", invoiceFile);
formData.append("name", "PO-123 Reconciliation");
formData.append("purchase_order_metadata", JSON.stringify({ po_number: "PO-123" }));
formData.append("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");
formData.append("metadata", JSON.stringify({ customer_id: "12345" }));
const response = await fetch("https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY"
},
body: formData
});
const flowRun = await response.json();
{
"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
string
required
The ID of the flow to run
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).string
Optional name for the flow run. This is useful for identifying flow runs in the TableFlow UI.
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.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.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"}'
import requests
import json
files = {
"purchase_order": open("po.pdf", "rb"),
"invoice": open("invoice.pdf", "rb")
}
data = {
"name": "PO-123 Reconciliation",
"purchase_order_metadata": json.dumps({"po_number": "PO-123"}),
"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",
"metadata": json.dumps({"customer_id": "12345"})
}
response = requests.post(
"https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run",
headers={
"Authorization": "Bearer YOUR_API_KEY"
},
files=files,
data=data
)
flow_run = response.json()
const formData = new FormData();
formData.append("purchase_order", purchaseOrderFile);
formData.append("invoice", invoiceFile);
formData.append("name", "PO-123 Reconciliation");
formData.append("purchase_order_metadata", JSON.stringify({ po_number: "PO-123" }));
formData.append("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");
formData.append("metadata", JSON.stringify({ customer_id: "12345" }));
const response = await fetch("https://api.tableflow.com/v2/flows/dk4g1tUg1uHLs8YU/run", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY"
},
body: formData
});
const flowRun = await response.json();
string
required
The unique identifier for the flow run
string
required
The ID of the flow being executed
string
required
The workspace ID
string
required
Current status of the flow run: processing, review, completed, or failed
array
required
string
Error message if the flow run failed
object
Custom metadata provided when running the flow
string
required
How the flow was triggered: api or manual
number
required
Unix timestamp when the flow run started
number
Unix timestamp when the flow run completed
number
required
Duration of the flow run in milliseconds
number
required
Unix timestamp when the flow run was created
number
required
Unix timestamp when the flow run was last updated