Start Batch Calls
Initiate a batch call operation using a CSV file and specified agent
Headers
x-workspace-idstringrequiredWorkspace identifier for the API.
The agent must have an active imported (bring-your-own) phone number. Numbers bought through Trillet cannot place batch calls. Without one, this endpoint returns 400 "Selected agent does not have an external active phone number".
Request Body
This endpoint accepts multipart/form-data with the following fields:
filefilerequiredCSV file containing the batch call data. Maximum file size: 20MB.
agentIdstringrequiredThe ID of the agent that will make the calls. It must belong to the workspace in x-workspace-id.
fromPhoneNumberIdstringID of the phone number to call from. It must be an active imported number assigned to the agent; otherwise the request returns 400. If omitted, the agent's numbers are used.
scheduledAtstringISO 8601 date-time to start the batch later, for example 2026-11-15T14:30:00Z. A value with no offset is read as UTC. If omitted, the batch starts immediately. An unparseable value returns 400.
scheduledTimezonestringIANA timezone the start time was chosen in (for example America/New_York). It is stored for display only and does not change when the batch runs. Unknown zones are ignored.
smartCallbackConfigstringJSON string that turns on outcome-based retries. Format: {"enabled": boolean, "maxAttempts": number, "gaps": [{"days": number, "hours": number}]}. days is 0-30 and hours 0-23. Without it (or with enabled: false), contacts are called once.
Testing Note: The "Try Now" button in this documentation doesn't support file uploads. Use the cURL example below or a tool like Postman to test this endpoint.
CSV File Format
- A phone number column named
phone_number,phoneorPhone(required). 10-digit US/Canada numbers get+1added; numbers must end up in E.164 format. - Any other columns are passed to the call as dynamic variables, referenced in the prompt as
{{column_name}}. - Rows with a missing or invalid phone number are skipped. If no row has a valid number, the request returns
400.
See Download Batch CSV Template for the template columns.
Response
batchIdstringUnique 10-character identifier for the batch, for example k3j9x0a1bq.
totalCallsnumberNumber of valid rows that will be called. Rows with errors are not counted.
statusstringqueued when the batch starts immediately, or scheduled when scheduledAt was sent.
messagestring"Batch calls queued successfully", or "Batch is scheduled to start at <ISO date-time>" for a scheduled batch.
Example Usage
# Basic batch call
curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID" \
-F "file=@batch-calls.csv" \
-F "agentId=a9a9a9a9a9a9a9a9a9a9a9a9"
# Scheduled batch call with smart callback
curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID" \
-F "file=@batch-calls.csv" \
-F "agentId=a9a9a9a9a9a9a9a9a9a9a9a9" \
-F "scheduledAt=2026-11-15T14:30:00Z" \
-F "scheduledTimezone=America/New_York" \
-F "smartCallbackConfig={\"enabled\": true, \"maxAttempts\": 3, \"gaps\": [{\"days\": 1, \"hours\": 0}]}"
Example Response
{
"batchId": "k3j9x0a1bq",
"totalCalls": 150,
"status": "queued",
"message": "Batch calls queued successfully"
}
Example Response (scheduled)
{
"batchId": "p8d2m4t7zs",
"totalCalls": 150,
"status": "scheduled",
"message": "Batch is scheduled to start at 2026-11-15T14:30:00.000Z"
}
Testing with Different Tools
# Basic usage
curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID" \
-F "file=@batch-calls.csv" \
-F "agentId=a9a9a9a9a9a9a9a9a9a9a9a9"
# With verbose output for debugging
curl -v -X POST "https://api.trillet.ai/v1/api/batch-calls" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID" \
-F "file=@batch-calls.csv" \
-F "agentId=a9a9a9a9a9a9a9a9a9a9a9a9"
# With scheduled time and smart callback
curl -X POST "https://api.trillet.ai/v1/api/batch-calls" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-workspace-id: YOUR_WORKSPACE_ID" \
-F "file=@batch-calls.csv" \
-F "agentId=a9a9a9a9a9a9a9a9a9a9a9a9" \
-F "scheduledAt=2026-11-15T14:30:00Z" \
-F "smartCallbackConfig={\"enabled\": true, \"maxAttempts\": 5, \"gaps\": [{\"days\": 1, \"hours\": 0}, {\"days\": 2, \"hours\": 0}]}"Processing Flow
- File Upload: The CSV file is uploaded
- Agent and Number Checks: The agent must be in your workspace and have an active imported number (or the
fromPhoneNumberIdyou named) - Record Validation: Each row is validated; rows with errors are dropped
- Queue Initialization: One call job is queued per valid row, or a single delayed job is created for a scheduled batch
- Execution: Calls are placed according to the call flow's settings (or at the scheduled time)
Error Responses
Errors return a JSON object with an error string.
| Status | When |
|---|---|
400 | "No file uploaded", "Agent ID is required", invalid scheduledAt, fromPhoneNumberId not an active imported number on the agent, agent has no active imported number, no valid phone numbers in the CSV (also returns validationErrors), or "CSV validation failed: ..." |
400 | "code": "INSUFFICIENT_FUNDS" when the wallet balance is spent |
402 | "code": "SPEND_CAP_REACHED" |
403 | Wallet not found, monthly limit exceeded, or the account's service has ended |
404 | "Agent with ID <id> not found": the agent doesn't exist or is in another workspace |
500 | "Failed to prepare batch: ...", "Failed to start batch: ..." |
Last updated on