Trillet AI logo

Start Batch Calls

Initiate a batch call operation using a CSV file and specified agent

POSThttps://api.trillet.ai/v1/api/batch-calls

Headers

x-workspace-idstringrequired

Workspace 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:

filefilerequired

CSV file containing the batch call data. Maximum file size: 20MB.

agentIdstringrequired

The ID of the agent that will make the calls. It must belong to the workspace in x-workspace-id.

fromPhoneNumberIdstring

ID 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.

scheduledAtstring

ISO 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.

scheduledTimezonestring

IANA 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.

smartCallbackConfigstring

JSON 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, phone or Phone (required). 10-digit US/Canada numbers get +1 added; 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

batchIdstring

Unique 10-character identifier for the batch, for example k3j9x0a1bq.

totalCallsnumber

Number of valid rows that will be called. Rows with errors are not counted.

statusstring

queued 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

  1. File Upload: The CSV file is uploaded
  2. Agent and Number Checks: The agent must be in your workspace and have an active imported number (or the fromPhoneNumberId you named)
  3. Record Validation: Each row is validated; rows with errors are dropped
  4. Queue Initialization: One call job is queued per valid row, or a single delayed job is created for a scheduled batch
  5. 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.

StatusWhen
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"
403Wallet 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