Start Batch Calls

POST

api

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

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"

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

const FormData = require('form-data');
const fs = require('fs');
const axios = require('axios');

const form = new FormData();
form.append('file', fs.createReadStream('batch-calls.csv'));
form.append('agentId', 'agent_123456');

const response = await axios.post('https://api.trillet.ai/v1/api/batch-calls', form, {
  headers: {
    ...form.getHeaders(),
    'x-api-key': 'YOUR_API_KEY',
    'x-workspace-id': 'YOUR_WORKSPACE_ID'
  }
});

import requests

url = "https://api.trillet.ai/v1/api/batch-calls"
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'x-workspace-id': 'YOUR_WORKSPACE_ID'
}

files = {
    'file': open('batch-calls.csv', 'rb'),
    'agentId': (None, 'agent_123456')
}

response = requests.post(url, headers=headers, files=files)
print(response.json())

Processing Flow

File Upload: The CSV file is uploaded and validated
Record Validation: Each record in the CSV is validated for required fields
Batch Preparation: A batch configuration is created with the specified agent
Queue Initialization: Individual call jobs are queued for processing
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.

Batch Calls Overview Get Batch Status

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>"
}

API Reference V1

Workspaces

Calls

Batch Calls

Telephony

Conversations

Folder Management

Call Flows

Message Flows

Call Agents

Omni Flow Agents (Message)

Headers

Request Body

CSV File Format

Response

Example Usage

Example Response

Testing with Different Tools

Processing Flow

Error Responses

Rate Limits

API Reference V1

Workspaces

Calls

Batch Calls

Telephony

Conversations

Folder Management

Call Flows

Message Flows

Call Agents

Omni Flow Agents (Message)

​Headers

​Request Body

​CSV File Format

​Response

​Example Usage

​Example Response

​Testing with Different Tools

​Processing Flow

​Error Responses

​Rate Limits

Headers

Request Body

CSV File Format

Response

Example Usage

Example Response

Testing with Different Tools

Processing Flow

Error Responses

Rate Limits