Upload File for Extraction

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\"}"

const axios = require("axios");
const FormData = require("form-data");
const fs = require("fs");

async function uploadFile(filePath, templateId, options = {}) {
  try {
    const form = new FormData();
    form.append("file", fs.createReadStream(filePath));
    form.append("template_id", templateId);

    if (options.name) {
      form.append("name", options.name);
    }

    if (options.guidance) {
      form.append("guidance", options.guidance);
    }

    if (options.metadata) {
      const metadataStr = typeof options.metadata === "string"
        ? options.metadata
        : JSON.stringify(options.metadata);
      form.append("metadata", metadataStr);
    }

    const response = await axios.post(
      "https://api.tableflow.com/v2/extractions/upload",
      form,
      {
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          ...form.getHeaders(),
        },
      }
    );

    console.log(response.data);
    return response.data;
  } catch (error) {
    console.error(error);
  }
}

// Example with name and metadata
uploadFile("/path/to/your/invoice.pdf", "dk4g1tUg1uHLs8YU", {
  name: "April 2023 Invoice",
  metadata: { user_id: "123", reference: "INV-2023-04-15", source: "web-app" },
});

import requests
import json

def upload_file(file_path, template_id, name=None, guidance=None, metadata=None):
    url = "https://api.tableflow.com/v2/extractions/upload"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY"
    }

    files = {
        "file": open(file_path, "rb")
    }

    data = {
        "template_id": template_id
    }

    if name:
        data["name"] = name

    if guidance:
        data["guidance"] = guidance

    if metadata:
        if isinstance(metadata, dict):
            data["metadata"] = json.dumps(metadata)
        else:
            data["metadata"] = metadata

    response = requests.post(url, headers=headers, files=files, data=data)

    return response.json()

# Example with name and metadata
extraction = upload_file(
    "/path/to/your/invoice.pdf",
    "dk4g1tUg1uHLs8YU",
    name="April 2023 Invoice",
    metadata={"user_id": "123", "reference": "INV-2023-04-15", "source": "python-client"}
)
print(extraction)

{
  "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
}

POST

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\"}"

const axios = require("axios");
const FormData = require("form-data");
const fs = require("fs");

async function uploadFile(filePath, templateId, options = {}) {
  try {
    const form = new FormData();
    form.append("file", fs.createReadStream(filePath));
    form.append("template_id", templateId);

    if (options.name) {
      form.append("name", options.name);
    }

    if (options.guidance) {
      form.append("guidance", options.guidance);
    }

    if (options.metadata) {
      const metadataStr = typeof options.metadata === "string"
        ? options.metadata
        : JSON.stringify(options.metadata);
      form.append("metadata", metadataStr);
    }

    const response = await axios.post(
      "https://api.tableflow.com/v2/extractions/upload",
      form,
      {
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          ...form.getHeaders(),
        },
      }
    );

    console.log(response.data);
    return response.data;
  } catch (error) {
    console.error(error);
  }
}

// Example with name and metadata
uploadFile("/path/to/your/invoice.pdf", "dk4g1tUg1uHLs8YU", {
  name: "April 2023 Invoice",
  metadata: { user_id: "123", reference: "INV-2023-04-15", source: "web-app" },
});

import requests
import json

def upload_file(file_path, template_id, name=None, guidance=None, metadata=None):
    url = "https://api.tableflow.com/v2/extractions/upload"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY"
    }

    files = {
        "file": open(file_path, "rb")
    }

    data = {
        "template_id": template_id
    }

    if name:
        data["name"] = name

    if guidance:
        data["guidance"] = guidance

    if metadata:
        if isinstance(metadata, dict):
            data["metadata"] = json.dumps(metadata)
        else:
            data["metadata"] = metadata

    response = requests.post(url, headers=headers, files=files, data=data)

    return response.json()

# Example with name and metadata
extraction = upload_file(
    "/path/to/your/invoice.pdf",
    "dk4g1tUg1uHLs8YU",
    name="April 2023 Invoice",
    metadata={"user_id": "123", "reference": "INV-2023-04-15", "source": "python-client"}
)
print(extraction)

{
  "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

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.

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.

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.

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.

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\"}"

const axios = require("axios");
const FormData = require("form-data");
const fs = require("fs");

async function uploadFile(filePath, templateId, options = {}) {
  try {
    const form = new FormData();
    form.append("file", fs.createReadStream(filePath));
    form.append("template_id", templateId);

    if (options.name) {
      form.append("name", options.name);
    }

    if (options.guidance) {
      form.append("guidance", options.guidance);
    }

    if (options.metadata) {
      const metadataStr = typeof options.metadata === "string"
        ? options.metadata
        : JSON.stringify(options.metadata);
      form.append("metadata", metadataStr);
    }

    const response = await axios.post(
      "https://api.tableflow.com/v2/extractions/upload",
      form,
      {
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
          ...form.getHeaders(),
        },
      }
    );

    console.log(response.data);
    return response.data;
  } catch (error) {
    console.error(error);
  }
}

// Example with name and metadata
uploadFile("/path/to/your/invoice.pdf", "dk4g1tUg1uHLs8YU", {
  name: "April 2023 Invoice",
  metadata: { user_id: "123", reference: "INV-2023-04-15", source: "web-app" },
});

import requests
import json

def upload_file(file_path, template_id, name=None, guidance=None, metadata=None):
    url = "https://api.tableflow.com/v2/extractions/upload"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY"
    }

    files = {
        "file": open(file_path, "rb")
    }

    data = {
        "template_id": template_id
    }

    if name:
        data["name"] = name

    if guidance:
        data["guidance"] = guidance

    if metadata:
        if isinstance(metadata, dict):
            data["metadata"] = json.dumps(metadata)
        else:
            data["metadata"] = metadata

    response = requests.post(url, headers=headers, files=files, data=data)

    return response.json()

# Example with name and metadata
extraction = upload_file(
    "/path/to/your/invoice.pdf",
    "dk4g1tUg1uHLs8YU",
    name="April 2023 Invoice",
    metadata={"user_id": "123", "reference": "INV-2023-04-15", "source": "python-client"}
)
print(extraction)

Response

string

The unique identifier for the new extraction.

string

The ID of the workspace this extraction belongs to.

string

The ID of the template used for the extraction.

string

The current status of the extraction, typically “processing” for a new upload.

object

Additional metadata associated with the extraction.

integer

Unix timestamp when the extraction was created.

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

string

Error message describing what went wrong.

{
  "error": "The parameter 'template_id' is required"
}

{
  "error": "No file was uploaded or the file is empty"
}

{
  "error": "File type '.xyz' is not supported. Supported types are: .pdf, .xlsx, .xls, .csv, .tsv, .jpg, .png, .webp, .tiff"
}

{
  "error": "File size 2305 MB exceeds limit of 1 GB"
}

{
  "error": "Invalid or missing API key"
}

What Happens After Upload

After successfully uploading a file, the extraction process follows these steps:

Processing - The file is being analyzed and data is being extracted
Completed - Data extraction has finished successfully
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)

List Extractions Extraction

​Usage Notes

​Request

​Response

​Error Responses

​What Happens After Upload

​File Type Support

​PDFs

​Spreadsheets

​Images

Usage Notes

Request

Response

Error Responses

What Happens After Upload

File Type Support

PDFs

Spreadsheets

Images