The Tofu API allows you to programmatically send invoice files and supporting documents into Tofu so they appear in the Source documents column and get processed for invoice extraction. This makes it easy to automate uploads or connect Tofu directly with your firm’s storage and communication tools.

What the Tofu API is for

The Tofu API scope is focused on document ingestion. You can:

Fetch Entities
Upload documents into Tofu directly via API.
Connect to storage providers or other sources (email, WhatsApp, etc.) and automatically ingest new files.
Fetch and download documents for upload and processing in Tofu

Authentication

All requests require an API key and most requests require an entity ID

API Key

Include your API key in the request header:

Tofu-API-Key: <your_key>

Entity ID

Include the entity_id query parameter on most endpoints.

Endpoints

Detail schema shown at the end.

Entities

List Entities

GET https://api.gotofu.com/api/v1/entities

Fetch all entities available to the authenticated user.

Get Entity by ID

GET https://api.gotofu.com/api/v1/entities/{entity_id}

Retrieve details for a specific entity.

Documents

Create Documents (Direct Upload)

POST https://api.gotofu.com/api/v1/documents

Upload one or more files directly to Tofu.

This endpoint supports multipart form uploads. Multiple files can be uploaded in a single request, such as one invoice and multiple supporting documents.

List Documents

GET https://api.gotofu.com/api/v1/documents

Retrieve a paginated list of documents for a given entity.

Get Document by ID

GET https://api.gotofu.com/api/v1/documents/{document_id}

Fetch details for a specific document.

Download Original Document

GET https://api.gotofu.com/api/v1/documents/{document_id}/download

Download the original uploaded file in binary format.

Processing Behavior

Uploads are queued and processed in the background.

Status transitions:

PENDING → PROCESSING → NEEDS_REVIEW | DONE | ERROR

Getting Started Checklist

✅ Generate an API key from your Tofu account.

✅ Fetch entities to get the entity_id you’ll be working with.

✅ Test a direct upload.

✅ Monitor the Source documents view in the Tofu app to see processed invoices.

Schema

List Entities

GET /api/v1/entities

Fetch all entities available to the authenticated user.

Response Body

{   "total_count": 1,   "data": [     {       "id": "uuid",       "name": "Acme Corp",       "slug": "acme-corp",       "country_id": "JP",       "accounting_write_sync_enabled": true,       "share_knowledge_opt_in": false,       "line_item_tax_amount_override_enabled": false,       "accounting_invoice_status_on_verify": "SUBMITTED",       "created_at": 1732112332000,       "updated_at": 1732112332000     }   ] }

Get Entity by ID

GET /api/v1/entities/{entity_id}

Retrieve details for a specific entity.

Path Parameters

entity_id (string, UUID, required) – Entity ID.

Response Body

{   "id": "uuid",   "name": "Acme Corp",   "slug": "acme-corp",   "country_id": "JP",   "accounting_write_sync_enabled": true,   "share_knowledge_opt_in": false,   "line_item_tax_amount_override_enabled": false,   "accounting_invoice_status_on_verify": "SUBMITTED",   "created_at": 1732112332000,   "updated_at": 1732112332000 }

List Documents

GET /api/v1/documents

Retrieve a paginated list of documents for a given entity.

Query Parameters

entity_id (string, UUID, required) – Entity ID.
n_per_page (integer, optional, default: 20, min: 1, max: 100) – Number of documents per page.
page_number (integer, optional, default: 0, min: 0) – Page index to fetch.

Response Body

{   "total_count": 2,   "data": [     {       "id": "uuid-1",       "file_name": "invoice1.pdf",       "mime_type": "application/pdf",       "size": 102400,       "entity_id": "uuid",       "status": "PROCESSING",       "checksum": "abc123xyz",       "original_document_id": null,       "source": "TOFU",       "created_at": 1732112332000,       "updated_at": 1732112332000     },     {       "id": "uuid-2",       "file_name": "receipt.jpg",       "mime_type": "image/jpeg",       "size": 204800,       "entity_id": "uuid",       "status": "DONE",       "checksum": "def456uvw",       "original_document_id": "uuid-1",       "source": "GOOGLE_DRIVE",       "created_at": 1732112332000,       "updated_at": 1732112332000     }   ] }

Get Document by ID

GET /api/v1/documents/{documentId}

Fetch details for a specific document.

Path Parameters

documentId (string, UUID, required) – Document ID.

Query Parameters

entity_id (string, UUID, required) – Entity ID.

Response Body

{   "id": "uuid-1",   "file_name": "invoice1.pdf",   "mime_type": "application/pdf",   "size": 102400,   "entity_id": "uuid",   "status": "PROCESSING",   "checksum": "abc123xyz",   "original_document_id": null,   "source": "TOFU",   "created_at": 1732112332000,   "updated_at": 1732112332000 }