Trillet AI logo

Batch AI calls API: outbound calls from a CSV

Use the batch AI calls API to place outbound AI calls to a list of contacts from a CSV: validate the file, start the batch, track progress and cancel calls.

The batch AI calls API places outbound AI calls to many contacts at once from a CSV file. Each row becomes a call, and the other columns in the row are passed to your agent as dynamic variables. Use it for appointment reminders, lead follow-up, surveys and other outbound campaigns.

Before you start

The agent must have an active imported (bring-your-own) phone number. Batch calls are not placed from numbers bought through Trillet. If the agent has no active imported number, Start Batch Calls returns 400 with "Selected agent does not have an external active phone number". To import a number, see Register External Number.

  • The agent must belong to the workspace in x-workspace-id. Agent IDs are 24-character IDs; any other value returns 404.
  • The workspace needs a positive wallet balance. Every batch endpoint except the template, validate and preview endpoints runs the wallet check, and returns 400 with "code": "INSUFFICIENT_FUNDS" when the balance is spent. This also applies to reading and cancelling batches.

Key Features

  • CSV-based data upload - Upload contact lists with custom fields for personalization
  • Template generation - Download a formatted CSV template
  • Data validation - Check your CSV before starting a batch
  • Monitoring - Track batch counters and individual call status
  • Batch management - Start, schedule and cancel batches, or cancel single contacts
  • Smart callbacks - Optionally retry contacts based on the call outcome

Workflow

1. Prepare Your Data

Download the template or build a CSV with a phone number column:

phone_number,business,contact_name,service,date,amount,notes
+14155550123,Acme Dental,John Smith,Cleaning,"November 12th, 2026",$120,Prefers mornings
+14155550187,Acme Dental,Jane Doe,Checkup,"November 14th, 2026",$90,

2. Validate the File (optional)

curl -X POST "https://api.trillet.ai/v1/api/batch-calls/validate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID" \
  -F "file=@your-contacts.csv"

3. Start the Batch

Upload the CSV and name the agent that will make the calls:

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=@your-contacts.csv" \
  -F "agentId=a9a9a9a9a9a9a9a9a9a9a9a9"

The response includes a batchId, a 10-character lowercase ID such as k3j9x0a1bq.

4. Monitor Progress

curl -X GET "https://api.trillet.ai/v1/api/batch-calls/k3j9x0a1bq" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

CSV File Requirements

Phone number column

  • The phone number column may be named phone_number, phone or Phone.
  • Spaces, dashes and brackets are removed.
  • A 10-digit US/Canada number (for example 4155550123) gets +1 added. An 11-digit number starting with 1 gets + added. Other digit-only numbers are treated as already including a country code and get + added.
  • After formatting, the number must be in E.164 format (+ followed by up to 15 digits).
  • Rows with a missing or invalid phone number are skipped: the batch runs for the valid rows only.

Other columns

Every other column is passed to the call as a dynamic variable, under the column name. Values longer than 500 characters produce a warning, not an error.

File Specifications

  • Maximum file size: 20MB
  • Supported format: CSV (Comma-Separated Values) with a header row
  • Encoding: UTF-8 recommended

Dynamic Variables

Each CSV column (other than the phone number) is available in your agent's prompt as a dynamic variable with double braces. For example, with a contact_name column:

"Hello {{contact_name}}, this is a reminder from {{business}} about your {{service}} on {{date}}."

Processing

  • Calls are queued and placed automatically. Pacing and office hours come from the agent's call flow settings.
  • Use scheduledAt on Start Batch Calls to start the batch later.
  • Calls are not retried unless you send a smartCallbackConfig with enabled: true. With smart callbacks on, follow-up attempts are scheduled from the call outcome, up to maxAttempts, using the gaps between attempts.

Status Tracking

Get Batch Status reports counters for:

  • waiting: calls queued but not yet started
  • active: calls currently being placed
  • completed: dial jobs that finished. This does not mean the conversation succeeded; read the outcome from Call History.
  • failed: dial jobs that failed

Live batch tracking is kept for 7 days. After that, Get Batch Status, Get Batch Progress and Get Individual Call Status no longer have data for the batch (Get Batch Status and Cancel return 404 Batch not found). For older batches use Call History filtered by batchId, List Batch Calls (which falls back to the stored batch record), or GET /v1/api/batch-history/batch/{batchId}.

Best Practices

Data Preparation

  • Run Validate Batch CSV first and fix rows with errors; they are skipped when the batch starts
  • Use E.164 numbers (+14155550123) to avoid formatting surprises
  • Include personalization columns your prompt uses
  • Test with a small batch before running large campaigns

Monitoring

  • Poll the batch status while it runs
  • Use Call History with batchId for call outcomes, transcripts and analysis
  • Cancel single contacts or the whole batch if issues are detected

Compliance

  • Ensure you have consent to call all numbers in your list
  • Respect do-not-call lists and regulations
  • Include opt-out mechanisms in your call scripts
  • Follow local telecommunications regulations

Testing with Postman

The documentation's "Try Now" buttons don't support file uploads. To test batch endpoints with Postman:

Start Batch Calls

  • Method: POST
  • URL: https://api.trillet.ai/v1/api/batch-calls
  • Headers:
    • x-api-key: YOUR_API_KEY
    • x-workspace-id: YOUR_WORKSPACE_ID
  • Body: form-data
    • Key: file, Type: File, Value: [Select your CSV file]
    • Key: agentId, Type: Text, Value: your_agent_id

Important: The documentation's interactive "Try Now" buttons cannot handle file uploads. Use cURL, Postman, or similar tools for endpoints that take a file.

Support

For technical support with batch call operations, contact our support team with your batch ID for faster assistance.

Last updated on