API Integration

What is an API?

An API (Application Programming Interface) is like a messenger that lets different software talk to each other. Instead of manually uploading documents through our website, you can write a small program that sends documents automatically.

This is useful if you want to:

Process many documents at once
Connect Tavnit to other tools you use
Build automated workflows

Credentials

API Key

Your API key is available in the Integrations tab after signing in.

Keep your API key secret. If you regenerate it from the Integrations tab, the previous key will be disabled.

Flow ID

The Flow ID can be found on each flow's details page. Use this when sending documents to a specific flow.

Collection ID

The Collection ID can be found on each collection's details page. Use this when you want AI to route documents to the best-matching flow.

Cleaner ID

The Cleaner ID can be found on each cleaner's details page. Use this when triggering a sweep to post-process or enrich extracted data.

Splitter ID

The Splitter ID can be found on each splitter's details page. Use this when sending documents to be split into individual document types.

Bucket ID & Name

Both required when writing to a bucket via API. Find them by tapping the info icon on the bucket's detail page. The name acts as a safety check to prevent accidental writes to the wrong bucket.

API URLs

Flows API (send to specific flow):

https://run.tavnit.io/api/runs/process

Collections API (AI routes to best flow):

https://run.tavnit.io/api/collections/process

Cleaners API (trigger a sweep):

https://run.tavnit.io/api/sweeps/run

Splitters API (split documents by type):

https://run.tavnit.io/api/splits/run

Buckets API (write rows to a bucket):

https://run.tavnit.io/api/buckets/write

Sending Documents

Tavnit accepts documents in two ways:

Multipart file upload

Send the file as binary data (classic file upload). Best when you have direct access to the file.

Base64-encoded file

Send the file content as a base64 string with a filename. Useful when working with automation tools or APIs that provide files as base64.

Both methods use the same endpoint and header:

URL: https://run.tavnit.io/api/runs/process
Header: X-API-Key: YOUR_API_KEY

Code Example

Select your preferred programming language:

Python

import requests

API_KEY = "YOUR_API_KEY"
FLOW_ID = "YOUR_FLOW_ID"

# ─────────────────────────────────────────────────────────────
# Option 1: Multipart file upload (binary)
# ─────────────────────────────────────────────────────────────
with open("document.pdf", "rb") as file:
    response = requests.post(
        "https://run.tavnit.io/api/runs/process",
        headers={"X-API-Key": API_KEY},
        data={
            "flow_id": FLOW_ID,
            "source": "api"
        },
        files={"file": file}
    )

print(response.json())


# ─────────────────────────────────────────────────────────────
# Option 2: Base64-encoded file (JSON body)
# ─────────────────────────────────────────────────────────────
import base64

with open("document.pdf", "rb") as file:
    file_base64 = base64.b64encode(file.read()).decode("utf-8")

response = requests.post(
    "https://run.tavnit.io/api/runs/process",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "flow_id": FLOW_ID,
        "source": "api",
        "filename": "document.pdf",
        "file_base64": file_base64
    }
)

print(response.json())

Collections API

Collections allow you to send documents without knowing which flow to use. AI analyzes each document and routes it to the most appropriate flow automatically.

When to use Collections API

Use this when you receive mixed document types (invoices, receipts, contracts, etc.) and want AI to determine the correct flow for each document.

The Collections API works the same as the Flows API, but uses a collection_id instead of flow_id:

URL: https://run.tavnit.io/api/collections/process
Header: X-API-Key: YOUR_API_KEY
Body: collection_id instead of flow_id

Python (Collections)

import requests

API_KEY = "YOUR_API_KEY"
COLLECTION_ID = "YOUR_COLLECTION_ID"

# ─────────────────────────────────────────────────────────────
# Option 1: Multipart file upload (binary)
# ─────────────────────────────────────────────────────────────
with open("document.pdf", "rb") as file:
    response = requests.post(
        "https://run.tavnit.io/api/collections/process",
        headers={"X-API-Key": API_KEY},
        data={
            "collection_id": COLLECTION_ID,
            "source": "api"
        },
        files={"file": file}
    )

print(response.json())


# ─────────────────────────────────────────────────────────────
# Option 2: Base64-encoded file (JSON body)
# ─────────────────────────────────────────────────────────────
import base64

with open("document.pdf", "rb") as file:
    file_base64 = base64.b64encode(file.read()).decode("utf-8")

response = requests.post(
    "https://run.tavnit.io/api/collections/process",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "collection_id": COLLECTION_ID,
        "source": "api",
        "filename": "document.pdf",
        "file_base64": file_base64
    }
)

print(response.json())

Learn more about Collections

See the Collections tab for a full explanation of how document routing works and how to set up collections in the app.

Cleaners API

Cleaners can be triggered via the API to run a sweep on a document or dataset. This is useful when you want to trigger enrichment or normalisation as part of an automated pipeline.

When to use the Cleaners API

Use this after a flow run to post-process or enrich the extracted values — for example normalising date formats, correcting spellings, or classifying values into categories.

The Cleaners API uses a cleaner_id and accepts a file to sweep:

URL: https://run.tavnit.io/api/sweeps/run
Header: X-API-Key: YOUR_API_KEY
Body: cleaner_id + file (multipart or base64)

Python (Cleaners)

import requests

api_key = "YOUR_API_KEY"
cleaner_id = "YOUR_CLEANER_ID"

# Option 1: multipart file upload
with open("document.pdf", "rb") as f:
    response = requests.post(
        "https://run.tavnit.io/api/sweeps/run",
        headers={"X-API-Key": api_key},
        data={"cleaner_id": cleaner_id, "source": "api"},
        files={"file": ("document.pdf", f, "application/pdf")},
    )

# Option 2: base64 string
import base64
with open("document.pdf", "rb") as f:
    encoded = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://run.tavnit.io/api/sweeps/run",
    headers={"X-API-Key": api_key, "Content-Type": "application/json"},
    json={"cleaner_id": cleaner_id, "source": "api",
          "filename": "document.pdf", "file_base64": encoded},
)

print(response.json())

Learn more about Cleaners

See the Cleaners tab for how to configure fields, extraction hints, and sweep results.

Splitters API

Splitters allow you to split multi-document PDFs into individual documents. AI classifies each page range and matches it to a document type defined in the splitter.

When to use Splitters API

Use this when you receive combined PDFs containing multiple document types (e.g., a stack of invoices, receipts, and contracts in a single file) and need them separated.

The Splitters API uses a splitter_id to identify which splitter to run:

URL: https://run.tavnit.io/api/splits/run
Header: X-API-Key: YOUR_API_KEY
Body: splitter_id + file (multipart or base64)

Python (Splitters)

import requests

API_KEY = "YOUR_API_KEY"
SPLITTER_ID = "YOUR_SPLITTER_ID"

# ─────────────────────────────────────────────────────────────
# Option 1: Multipart file upload (binary)
# ─────────────────────────────────────────────────────────────
with open("document.pdf", "rb") as file:
    response = requests.post(
        "https://run.tavnit.io/api/splits/run",
        headers={"X-API-Key": API_KEY},
        data={
            "splitter_id": SPLITTER_ID,
            "source": "api"
        },
        files={"file": file}
    )

print(response.json())


# ─────────────────────────────────────────────────────────────
# Option 2: Base64-encoded file (JSON body)
# ─────────────────────────────────────────────────────────────
import base64

with open("document.pdf", "rb") as file:
    file_base64 = base64.b64encode(file.read()).decode("utf-8")

response = requests.post(
    "https://run.tavnit.io/api/splits/run",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "splitter_id": SPLITTER_ID,
        "source": "api",
        "filename": "document.pdf",
        "file_base64": file_base64
    }
)

print(response.json())

Learn more about Splitters

See the Splitters section for details on how to configure document types and output actions.

Buckets API

Write rows of data directly into a bucket programmatically — useful for syncing data from external systems or pushing records without going through a flow.

When to use the Buckets API

Use this when you want to insert or replace rows in a bucket from your own application, a database, or an automation tool — independent of any flow run.

URL: https://run.tavnit.io/api/buckets/write
Header: X-API-Key: YOUR_API_KEY
Body: bucket_id, bucket_name, overwrite (bool), rows (array)

Python (Buckets)

import requests

API_KEY = "YOUR_API_KEY"
BUCKET_ID = "YOUR_BUCKET_ID"
BUCKET_NAME = "YOUR_BUCKET_NAME"

# ─────────────────────────────────────────────────────────────
# Append rows to existing data (overwrite=False)
# ─────────────────────────────────────────────────────────────
response = requests.post(
    "https://run.tavnit.io/api/buckets/write",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "bucket_id": BUCKET_ID,
        "bucket_name": BUCKET_NAME,
        "overwrite": False,
        "rows": [
            {"invoice_number": "INV-1001", "vendor": "Acme Corp", "amount": 1200.50},
            {"invoice_number": "INV-1002", "vendor": "Globex", "amount": 430.00}
        ]
    }
)

print(response.json())


# ─────────────────────────────────────────────────────────────
# Replace all rows (overwrite=True)
# ─────────────────────────────────────────────────────────────
response = requests.post(
    "https://run.tavnit.io/api/buckets/write",
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    },
    json={
        "bucket_id": BUCKET_ID,
        "bucket_name": BUCKET_NAME,
        "overwrite": True,
        "rows": [
            {"invoice_number": "INV-3001", "vendor": "NewCo", "amount": 400.00}
        ]
    }
)

print(response.json())

Learn more about Buckets

See the Buckets tab for column setup, access control, charts, and CSV import/export.

Automation Tools Overview

You don't need to write code to integrate Tavnit with your workflows. No-code automation platforms let you connect apps visually and build powerful automations.

Popular no-code platforms that work with Tavnit:

Make.com

Visual automation platform with 1000+ app integrations. Great for complex multi-step workflows.

Zapier

Connect Tavnit to 5000+ apps with simple “Zaps”. Perfect for straightforward automations.

n8n

Open-source workflow automation. Self-host or use their cloud service for full control.

All of these platforms support HTTP requests, which means they can send documents to Tavnit's API.

Make.com Integration

Make.com (formerly Integromat) is a visual automation platform that lets you connect apps and automate workflows without writing any code.

Visit Make.com

Getting Started with Make.com

1Go to make.com and create a free account
2Click "Create a new scenario" from your dashboard
3You'll see a blank canvas where you can add modules
4Search for "HTTP" and add the "Make a request" module

What is a Scenario?

A scenario is an automated workflow in Make.com. It consists of modules (apps) connected together. When one module triggers or receives data, it passes that data to the next module.

Configure the HTTP Module

Once you've added the HTTP module, configure it to send documents to Tavnit. You can use either of these two approaches:

Option 1: Multipart/form-data (when you have a File object)

1Add an HTTP "Make a request" module to your scenario
2
Configure the request:
- URL: https://run.tavnit.io/api/runs/process
- Method: POST
3
In the Headers tab, add:
- Header name: X-API-Key
- Header value: YOUR_API_KEY
4Set Body type to "multipart/form-data"
5
Add form fields:
- flow_id: YOUR_FLOW_ID
- source: api
- file: (map from previous module)
6Run your scenario to test

Option 2: JSON + base64 (when you have a base64 string)

If your previous module outputs a base64 string instead of a file, use this approach:

1Set Body type to "Raw" and select "JSON (application/json)"
2
In the Headers tab, also add:
- Header name: Content-Type
- Header value: application/json
3Set the JSON body to:

JSON

{
  "flow_id": "YOUR_FLOW_ID",
  "source": "api",
  "filename": "document.pdf",
  "file_base64": "{{previous_module.base64_content}}"
}

Mapping the base64 content

Replace {{previous_module.base64_content}} with the actual mapping from your previous module. In Make.com, click in the field and select the base64 output from the module that provides your file.

Other Platforms (Zapier, Power Automate, n8n)

The same approach works for any automation platform that supports HTTP requests:

If your platform gives you a file object

Use multipart/form-data with a “file” field containing the file, plus flow_id and source fields.

If your platform gives you a base64 string

Use a JSON body with flow_id, source, filename, and file_base64 (the base64 content from the previous step).

Both methods call the same endpoint and produce identical extraction results.

Using Collections API

If you receive different types of documents (invoices, receipts, contracts, etc.) and want AI to automatically route each document to the right flow, use the Collections API instead.

Collections vs Flows

Flows API: You specify which flow to use with flow_id. Collections API: AI analyzes the document and picks the best flow automatically using collection_id.

The setup is identical to the Flows API above, with two small changes:

URL: https://run.tavnit.io/api/collections/process
Use collection_id instead of flow_id in your request body

Example JSON body for Collections:

JSON

{
  "collection_id": "YOUR_COLLECTION_ID",
  "source": "api",
  "filename": "document.pdf",
  "file_base64": "{{previous_module.base64_content}}"
}

Using Cleaners API

If you want to enrich or normalise extracted data after a flow run, use the Cleaners API to trigger a sweep programmatically from your automation tool.

Cleaners vs Flows

Flows API: Extracts raw data from a document. Cleaners API: Post-processes that data — normalising, classifying, or enriching field values.

Configuration in your HTTP module:

URL: https://run.tavnit.io/api/sweeps/run
Use cleaner_id instead of flow_id in your request body

Example JSON body for Cleaners:

JSON

{
  "cleaner_id": "YOUR_CLEANER_ID",
  "source": "api",
  "filename": "document.pdf",
  "file_base64": "{{previous_module.base64_content}}"
}

Using Splitters API

If you receive combined PDFs containing multiple document types and need them separated into individual files, use the Splitters API.

Splitters vs Flows

Flows API: Extracts data from a single document using flow_id. Splitters API: Splits a multi-document PDF into individual documents using splitter_id.

The setup is similar to the Flows API, with these changes:

URL: https://run.tavnit.io/api/splits/run
Use splitter_id instead of flow_id in your request body

Example JSON body for Splitters:

JSON

{
  "splitter_id": "YOUR_SPLITTER_ID",
  "source": "api",
  "filename": "combined_docs.pdf",
  "file_base64": "{{previous_module.base64_content}}"
}

Using Buckets API

If you want to push rows of data into a bucket from your automation tool — without sending a document for extraction — use the Buckets Write API.

Buckets vs Flows

Flows API: Sends a document for AI extraction. Buckets API: Writes structured rows directly into a bucket table.

Configuration in your HTTP module:

URL: https://run.tavnit.io/api/buckets/write
Method: POST, Content-Type: application/json
Header: X-API-Key: YOUR_API_KEY

Example JSON body:

JSON

{
  "bucket_id": "YOUR_BUCKET_ID",
  "bucket_name": "YOUR_BUCKET_NAME",
  "overwrite": false,
  "rows": [
    { "column_one": "value", "column_two": 123 }
  ]
}

Finding your Bucket ID & Name

Open the bucket's detail page and tap the info icon. Both values are copyable with a single tap.