Skip to main content
POST
/
v2
/
extractions
/
upload
curl -X POST https://api.tableflow.com/v2/extractions/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@/path/to/your/invoice.pdf" \
-F "template_id=dk4g1tUg1uHLs8YU" \
-F "name=April 2023 Invoice" \
-F "metadata={\"user_id\":\"123\",\"reference\":\"INV-2023-04-15\"}"

{
  "id": "uT2bJNWN75YPU95r",
  "workspace_id": "dk4g1tUg1uHLs8YU",
  "template_id": "JlLZVabDjYWzu7C9",
  "status": "processing",
  "metadata": {
    "user_id": "123",
    "reference": "INV-2023-04-15"
  },
  "created_at": 1682366228,
  "updated_at": 1682366228
}
Uploads a file and initiates an extraction process using the specified template.

​
Usage Notes

  • Maximum file size: 1GB
  • Files are processed according to the specified template
  • Use the metadata parameter to include custom data (like user IDs, reference numbers) that will be preserved across all extraction API responses and webhooks
  • Metadata is useful for tying back extractions to your systems, correlation, and application integration purposes
  • Configure webhooks for asynchronous notifications when extractions complete

​
Request

​
file
file
required
The file to upload and process. Supported formats include PDF (.pdf), Excel (.xlsx, .xls), CSV (.csv), TSV (.tsv), and image files (.jpg, .png, .webp, .tiff). Only one file can be uploaded per request.
​
template_id
string
required
The ID of the template to use for mapping the document data during extraction. You can also pass "auto" and TableFlow will automatically select the best template based on the document content and template file type settings.
​
name
string
Optional name for the extraction. This is useful for identifying extractions in the TableFlow UI and can be used to label extractions in your workflow.
​
guidance
string
Optional extraction guidance to provide additional context to the AI during extraction. Use this to give hints about the document structure, specific values to look for, or any other information that might help improve extraction accuracy.
​
metadata
string
Optional JSON string containing custom metadata to associate with this extraction. This can include any information you need to reference, such as user IDs, order numbers, or other contextual data. The metadata will be included in all extraction responses (API endpoints and webhooks), making it useful for correlating extractions with your application.Example: {"user_id": "123", "reference": "INV-2023-04-15", "source": "mobile-app"}
curl -X POST https://api.tableflow.com/v2/extractions/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@/path/to/your/invoice.pdf" \
-F "template_id=dk4g1tUg1uHLs8YU" \
-F "name=April 2023 Invoice" \
-F "metadata={\"user_id\":\"123\",\"reference\":\"INV-2023-04-15\"}"

​
Response

​
id
string
The unique identifier for the new extraction.
​
workspace_id
string
The ID of the workspace this extraction belongs to.
​
template_id
string
The ID of the template used for the extraction.
​
status
string
The current status of the extraction, typically “processing” for a new upload.
​
metadata
object
Additional metadata associated with the extraction.
​
created_at
integer
Unix timestamp when the extraction was created.
​
updated_at
integer
Unix timestamp when the extraction was last updated.
{
  "id": "uT2bJNWN75YPU95r",
  "workspace_id": "dk4g1tUg1uHLs8YU",
  "template_id": "JlLZVabDjYWzu7C9",
  "status": "processing",
  "metadata": {
    "user_id": "123",
    "reference": "INV-2023-04-15"
  },
  "created_at": 1682366228,
  "updated_at": 1682366228
}

​
Error Responses

​
error
string
Error message describing what went wrong.
{
  "error": "The parameter 'template_id' is required"
}

​
What Happens After Upload

After successfully uploading a file, the extraction process follows these steps:
  1. Processing - The file is being analyzed and data is being extracted
  2. Completed - Data extraction has finished successfully
  3. Failed - An error occurred during extraction
You can check the status of an extraction using the Get Extraction endpoint: 
curl -X GET https://api.tableflow.com/v2/extractions/uT2bJNWN75YPU95r \
  -H "Authorization: Bearer YOUR_API_KEY"
For real-time notifications when extractions complete, configure webhooks to receive events.

​
File Type Support

TableFlow supports the following file types:

​
PDFs

  • Digital (text-based) PDFs
  • Scanned (image-based) PDFs
  • Multi-page documents

​
Spreadsheets

  • Excel files (.xlsx, .xls)
  • CSV files (.csv)
  • TSV files (.tsv)
  • Multi-sheet workbooks

​
Images

  • JPEG files (.jpg)
  • PNG files (.png)
  • WebP files (.webp)
  • TIFF files (.tiff)