> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tableflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload File for Extraction

> Upload a file and trigger an extraction run

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

<ParamField body="file" type="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.
</ParamField>

<ParamField body="template_id" type="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.
</ParamField>

<ParamField body="name" type="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.
</ParamField>

<ParamField body="guidance" type="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.
</ParamField>

<ParamField body="metadata" type="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"}`
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  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\"}"
  ```

  ```javascript Node.js theme={null}
  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" },
  });
  ```

  ```python Python theme={null}
  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)
  ```
</RequestExample>

## Response

<ResponseField name="id" type="string">
  The unique identifier for the new extraction.
</ResponseField>

<ResponseField name="workspace_id" type="string">
  The ID of the workspace this extraction belongs to.
</ResponseField>

<ResponseField name="template_id" type="string">
  The ID of the template used for the extraction.
</ResponseField>

<ResponseField name="status" type="string">
  The current status of the extraction, typically "processing" for a new upload.
</ResponseField>

<ResponseField name="metadata" type="object">
  Additional metadata associated with the extraction.
</ResponseField>

<ResponseField name="created_at" type="integer">
  Unix timestamp when the extraction was created.
</ResponseField>

<ResponseField name="updated_at" type="integer">
  Unix timestamp when the extraction was last updated.
</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "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
  }
  ```
</ResponseExample>

## Error Responses

<ResponseField name="error" type="string">
  Error message describing what went wrong.
</ResponseField>

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "The parameter 'template_id' is required"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "No file was uploaded or the file is empty"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "File type '.xyz' is not supported. Supported types are: .pdf, .xlsx, .xls, .csv, .tsv, .jpg, .png, .webp, .tiff"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "File size 2305 MB exceeds limit of 1 GB"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid or missing API key"
  }
  ```
</ResponseExample>

## 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](/api-reference/get-extraction) endpoint:

```bash theme={null}
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](/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)