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 "metadata={\"user_id\":\"123\",\"reference\":\"INV-2023-04-15\"}"

{
  "id": "uT2bJNWN75YPU95r",
  "workspace_id": "dk4g1tUg1uHLs8YU",
  "template_id": "f150a878-bd38-4e18-9428-a22878a21ff4",
  "status": "processing",
  "metadata": {
    "name": "acme-invoice-apr2023.pdf",
    "user_id": "123",
    "reference": "INV-2023-04-15",
    "source": "web-app"
  },
  "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), and CSV (.csv). 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.

​
filename
string

Optional custom filename to use for the uploaded file. If not provided, the original filename will be used.

​
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 "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. You can also use auto as the template_id and TableFlow will select the best template based on the template’s allowed file types.

​
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": "f150a878-bd38-4e18-9428-a22878a21ff4",
  "status": "processing",
  "metadata": {
    "name": "acme-invoice-apr2023.pdf",
    "user_id": "123",
    "reference": "INV-2023-04-15",
    "source": "web-app"
  },
  "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)
  • Multi-sheet workbooks