POST
/
v1
/
api
/
batch-calls
Start Batch Calls
curl --request POST \
  --url https://api.trillet.ai/v1/api/batch-calls \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-workspace-id: <x-workspace-id>' \
  --data '{
  "agentId": "<string>"
}'
{
  "batchId": "<string>",
  "totalCalls": 123,
  "status": "<string>",
  "message": "<string>",
  "error": "<string>"
}

​
Headers

​
x-api-key
string
required
API key used for authenticating requests to the API.
​
x-workspace-id
string
required
Workspace identifier for the API.

​
Request Body

This endpoint accepts multipart/form-data with the following fields:
​
file
file
required
CSV file containing the batch call data. Maximum file size: 20MB.
​
agentId
string
required
The ID of the agent that will be used to make the batch calls.
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

The CSV file should contain the following columns:
  • phone_number - The phone number to call (required)
  • first_name - First name for personalization
  • last_name - Last name for personalization
  • email - Email address
  • Additional custom fields for dynamic variables

​
Response

​
batchId
string
Unique identifier for the batch call operation
​
totalCalls
number
Total number of calls that will be made in this batch
​
status
string
Current status of the batch operation (e.g., “queued”, “processing”)
​
message
string
Success message confirming the batch initiation

​
Example 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=agent_123456"

​
Example Response

{
  "batchId": "batch_7891011121314",
  "totalCalls": 150,
  "status": "queued",
  "message": "Batch calls initiated successfully"
}

​
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=agent_123456"

# 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=agent_123456"

​
Processing Flow

  1. File Upload: The CSV file is uploaded and validated
  2. Record Validation: Each record in the CSV is validated for required fields
  3. Batch Preparation: A batch configuration is created with the specified agent
  4. Queue Initialization: Individual call jobs are queued for processing
  5. Execution: Calls are made according to your account’s rate limits

​
Error Responses

​
error
string
Error message describing what went wrong
Common Error Codes:
  • 400 - No file uploaded, no agent ID provided, or CSV validation failed
  • 413 - File size exceeds 20MB limit
  • 500 - Failed to prepare batch or start batch execution

​
Rate Limits

Batch calls are subject to your account’s rate limits. The system will automatically manage the call queue to respect these limits while maximizing throughput.