TransfAI API Documentation

Authentication

All API requests require a Bearer token in the Authorization header. Your API key is unique to your account — keep it secret and never expose it in client-side code.

How to get your API key

Log in at app.transf.ai
Go to Settings → API Key
Click Generate key
Copy your key — it starts with sk-

Authentication request

GET /api/zapier/auth/test
Authorization: Bearer YOUR_API_KEY

Success response

{
  "id": "acc_123",
  "email": "you@yourbusiness.com",
  "business_name": "Your Business",
  "plan": "growth",
  "message": "Connected to TransfAI successfully"
}

Triggers

Triggers let you detect when events happen in TransfAI. Poll these endpoints on a schedule (every 15 minutes is recommended) to receive updates.

Agent Run Completed

GET/api/zapier/triggers/agent-runs

Returns recent agent runs. Poll this endpoint every 15 minutes to detect when agents complete. Results are ordered by most recent first.

Query parameters

Parameter	Type	Required	Description
agent_name	string	No	Filter by agent name (e.g. "Invoice Chaser")
status	string	No	Filter by status: success \| failed \| all (default: all)

Response

[
  {
    "id": "run_abc123",
    "agent_name": "Invoice Chaser",
    "status": "success",
    "contacts_actioned": 3,
    "started_at": "2026-06-18T10: 00: 00Z",
    "completed_at": "2026-06-18T10: 00: 05Z",
    "log_output": "Sent 3 invoice reminders"
  }
]

New Contact

GET/api/zapier/triggers/contacts

Returns recently added contacts. Poll every 15 minutes to detect new contacts added to your TransfAI account.

Response

[
  {
    "id": "contact_xyz789",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "phone": "+15551234567",
    "company": "Acme Corp",
    "created_at": "2026-06-18T10: 00: 00Z"
  }
]

Actions

Actions let you create and trigger things in TransfAI from external tools.

Run Agent

POST/api/zapier/actions/run-agent

Trigger any TransfAI AI agent to run immediately for a specific contact or context.

Request body

Parameter	Type	Required	Description
agent_id	string	Yes	The ID of the agent to run
contact_email	string	No	Email of the contact to run the agent for
context	string	No	Optional additional context or instructions

{
  "agent_id": "agent_abc123",
  "contact_email": "customer@example.com",
  "context": "Optional additional context"
}

Response

{
  "id": "run_xyz789",
  "agent_name": "Invoice Chaser",
  "status": "triggered",
  "message": "Agent run started successfully"
}

Add Contact

POST/api/zapier/actions/add-contact

Add or update a contact in TransfAI. If a contact with the given email already exists, their details are updated instead.

Request body

Parameter	Type	Required	Description
email	string	Yes	Contact email address (used as unique identifier)
first_name	string	No	Contact first name
last_name	string	No	Contact last name
phone	string	No	Phone number in E.164 format (e.g. +15551234567)
company	string	No	Company or business name
tags	string	No	Comma-separated tags (e.g. "lead, website")

{
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Smith",
  "phone": "+15551234567",
  "company": "Acme Corp",
  "tags": "lead, website"
}

Response

{
  "id": "contact_abc123",
  "email": "john@example.com",
  "first_name": "John",
  "created_at": "2026-06-18T10: 00: 00Z"
}

Search

Search endpoints let you look up specific records by ID, enabling you to fetch or verify individual resources.

Find Agent Run

GET/api/zapier/searches/agent-run/{id}

Look up a specific agent run by its ID. Returns full details including status, timing, and output.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The agent run ID (e.g. run_abc123)

Response

{
  "id": "run_abc123",
  "agent_name": "Invoice Chaser",
  "status": "success",
  "contacts_actioned": 3,
  "started_at": "2026-06-18T10: 00: 00Z",
  "completed_at": "2026-06-18T10: 00: 05Z"
}

Webhooks coming soon

TransfAI can push real-time notifications to your app when events occur, rather than requiring you to poll. Register a webhook URL in Settings → Developer Settings.

Available events

agent.run.completedFired when any agent finishes running

contact.createdFired when a new contact is added

contact.updatedFired when contact details change

trial.expiringFired 3 days before trial ends

Rate Limits

Rate limits protect API stability. If you exceed them, requests return 429 Too Many Requests.

Per minute

100 requests

Per hour

1,000 requests

Bulk ops

10 req/sec

Rate limit headers

Every response includes these headers so you can track your usage:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1718704800

Error Codes

TransfAI uses standard HTTP status codes. Errors include a message field with a human-readable description.

Code	Status	Meaning
200	OK	Request successful
400	Bad Request	Invalid parameters or malformed request body
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded — wait before retrying
500	Internal Server Error	Server error — contact support if persists

Error response format

{
  "error": "Unauthorized",
  "message": "Invalid API key. Check your key in Settings → API Key.",
  "status": 401
}

Code Examples

Full working examples for fetching agent runs. Replace YOUR_API_KEY with your key from Settings.

curl -X GET \
  https://app.transf.ai/api/zapier/triggers/agent-runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Ready to integrate?

Generate your API key in Settings and connect TransfAI to Zapier, Make, or any tool that speaks REST.

Get API key →Connect on Zapier

Authentication

All API requests require a Bearer token in the Authorization header. Your API key is unique to your account — keep it secret and never expose it in client-side code.

How to get your API key

Log in at app.transf.ai
Go to Settings → API Key
Click Generate key
Copy your key — it starts with sk-

Authentication request

GET /api/zapier/auth/test
Authorization: Bearer YOUR_API_KEY

Success response

{
  "id": "acc_123",
  "email": "you@yourbusiness.com",
  "business_name": "Your Business",
  "plan": "growth",
  "message": "Connected to TransfAI successfully"
}

Triggers

Triggers let you detect when events happen in TransfAI. Poll these endpoints on a schedule (every 15 minutes is recommended) to receive updates.

Agent Run Completed

GET/api/zapier/triggers/agent-runs

Returns recent agent runs. Poll this endpoint every 15 minutes to detect when agents complete. Results are ordered by most recent first.

Query parameters

Parameter	Type	Required	Description
agent_name	string	No	Filter by agent name (e.g. "Invoice Chaser")
status	string	No	Filter by status: success \| failed \| all (default: all)

Response

[
  {
    "id": "run_abc123",
    "agent_name": "Invoice Chaser",
    "status": "success",
    "contacts_actioned": 3,
    "started_at": "2026-06-18T10: 00: 00Z",
    "completed_at": "2026-06-18T10: 00: 05Z",
    "log_output": "Sent 3 invoice reminders"
  }
]

New Contact

GET/api/zapier/triggers/contacts

Returns recently added contacts. Poll every 15 minutes to detect new contacts added to your TransfAI account.

Response

[
  {
    "id": "contact_xyz789",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "phone": "+15551234567",
    "company": "Acme Corp",
    "created_at": "2026-06-18T10: 00: 00Z"
  }
]

Actions

Actions let you create and trigger things in TransfAI from external tools.

Run Agent

POST/api/zapier/actions/run-agent

Trigger any TransfAI AI agent to run immediately for a specific contact or context.

Request body

Parameter	Type	Required	Description
agent_id	string	Yes	The ID of the agent to run
contact_email	string	No	Email of the contact to run the agent for
context	string	No	Optional additional context or instructions

{
  "agent_id": "agent_abc123",
  "contact_email": "customer@example.com",
  "context": "Optional additional context"
}

Response

{
  "id": "run_xyz789",
  "agent_name": "Invoice Chaser",
  "status": "triggered",
  "message": "Agent run started successfully"
}

Add Contact

POST/api/zapier/actions/add-contact

Add or update a contact in TransfAI. If a contact with the given email already exists, their details are updated instead.

Request body

Parameter	Type	Required	Description
email	string	Yes	Contact email address (used as unique identifier)
first_name	string	No	Contact first name
last_name	string	No	Contact last name
phone	string	No	Phone number in E.164 format (e.g. +15551234567)
company	string	No	Company or business name
tags	string	No	Comma-separated tags (e.g. "lead, website")

{
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Smith",
  "phone": "+15551234567",
  "company": "Acme Corp",
  "tags": "lead, website"
}

Response

{
  "id": "contact_abc123",
  "email": "john@example.com",
  "first_name": "John",
  "created_at": "2026-06-18T10: 00: 00Z"
}

Search

Search endpoints let you look up specific records by ID, enabling you to fetch or verify individual resources.

Find Agent Run

GET/api/zapier/searches/agent-run/{id}

Look up a specific agent run by its ID. Returns full details including status, timing, and output.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	The agent run ID (e.g. run_abc123)

Response

{
  "id": "run_abc123",
  "agent_name": "Invoice Chaser",
  "status": "success",
  "contacts_actioned": 3,
  "started_at": "2026-06-18T10: 00: 00Z",
  "completed_at": "2026-06-18T10: 00: 05Z"
}

Webhooks coming soon

TransfAI can push real-time notifications to your app when events occur, rather than requiring you to poll. Register a webhook URL in Settings → Developer Settings.

Available events

agent.run.completedFired when any agent finishes running

contact.createdFired when a new contact is added

contact.updatedFired when contact details change

trial.expiringFired 3 days before trial ends

Rate Limits

Rate limits protect API stability. If you exceed them, requests return 429 Too Many Requests.

Per minute

100 requests

Per hour

1,000 requests

Bulk ops

10 req/sec

Rate limit headers

Every response includes these headers so you can track your usage:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1718704800

Error Codes

TransfAI uses standard HTTP status codes. Errors include a message field with a human-readable description.

Code	Status	Meaning
200	OK	Request successful
400	Bad Request	Invalid parameters or malformed request body
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded — wait before retrying
500	Internal Server Error	Server error — contact support if persists

Error response format

{
  "error": "Unauthorized",
  "message": "Invalid API key. Check your key in Settings → API Key.",
  "status": 401
}

Code Examples

Full working examples for fetching agent runs. Replace YOUR_API_KEY with your key from Settings.

curl -X GET \
  https://app.transf.ai/api/zapier/triggers/agent-runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Ready to integrate?

Generate your API key in Settings and connect TransfAI to Zapier, Make, or any tool that speaks REST.

Get API key →Connect on Zapier