Launch outbound calls

Use this guide when your CRM, data warehouse, or backend decides who to call and you want Callers to do the calling. You build the agent once in the dashboard, then your system pushes contacts, controls when the agent runs, and receives every outcome by webhook.

Before you begin

An outbound Voice agent with a script, voice, phone number, availability hours, and success criteria. Build and test it in the dashboard first; it’s easier than defining a full agent through the API.
An API key (create one) and the agent’s ID. See the API quickstart if you haven’t made a request yet.
A webhook endpoint. See Webhooks overview.

How outbound dialing works

Once an agent is active, Callers continuously picks eligible contacts and calls them:

Calls only go out inside the agent’s availability hours, in the agent’s time zone or the contact’s time zone if Use Contact’s Time Zone is on.
Unanswered, busy, and voicemail attempts are retried according to the agent’s retry settings (total attempts, minimum wait between attempts, maximum attempts per day).
Concurrency is capped by the agent’s Max Outgoing Calls in Parallel setting.
Contacts on your Do Not Call list are skipped.
Contacts you add while the agent is running are picked up automatically.
When no eligible contacts remain, the agent stops on its own. Adding new contacts to a completed agent makes it eligible to run again; call start if it’s stopped.

Step 1: Map your data to variables

Every key in a contact’s data object becomes a variable your script can use as {{key}}. Before sending contacts, list the variables your script uses and make sure each contact provides them.

Rule	Limit
Value type	Strings only. Convert numbers, dates, and booleans to strings.
Key format	Starts with a letter, `$`, or `_`; contains only letters, digits, `$`, `_`. `first_name` works, `first name` doesn’t.
Key length	Up to 120 characters.
Number of keys	Up to 100 per contact.
Total size	Up to 4,000 characters per contact (keys plus values).
Characters	No control characters except tab and line breaks.

Variables marked required in the agent must be present. A single-contact request missing one fails with 400; in a bulk request the incomplete contact is skipped.

Send a timezone (IANA name such as America/Chicago) per contact if you know it. Otherwise Callers detects the time zone from the phone number.

Step 2: Push contacts

Use the bulk endpoint for anything beyond a single contact. JSON bodies are limited to 1 MB, so split large lists into batches (a few hundred to a thousand contacts per request, depending on how much data each carries) and send them sequentially.

curl -X POST "https://api.callers.ai/agents/$AGENT_ID/contacts/bulk?verbose=true" \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "name": "Dana Levi",
        "phoneNumber": "+14155552671",
        "timezone": "America/Los_Angeles",
        "data": { "first_name": "Dana", "plan_renewal_date": "2026-11-30", "crm_id": "0035e00000AbCdE" }
      }
    ]
  }'

const API = "https://api.callers.ai";
const headers = {
  Authorization: process.env.CALLERS_API_KEY,
  "Content-Type": "application/json",
};

async function pushContacts(agentId, contacts, batchSize = 500) {
  const results = [];
  for (let i = 0; i < contacts.length; i += batchSize) {
    const batch = contacts.slice(i, i + batchSize);
    const res = await fetch(`${API}/agents/${agentId}/contacts/bulk?verbose=true`, {
      method: "POST",
      headers,
      body: JSON.stringify({ contacts: batch }),
    });
    const body = await res.json();
    if (!res.ok) throw new Error(`${res.status}: ${body.message}`);
    results.push(...body.data.contactDetails);
  }
  return results; // [{ contactId, phoneNumber, status: "created" | "updated" }]
}

import os
import requests

API = "https://api.callers.ai"
HEADERS = {"Authorization": os.environ["CALLERS_API_KEY"]}

def push_contacts(agent_id, contacts, batch_size=500):
    results = []
    for i in range(0, len(contacts), batch_size):
        res = requests.post(
            f"{API}/agents/{agent_id}/contacts/bulk",
            headers=HEADERS,
            params={"verbose": "true"},
            json={"contacts": contacts[i : i + batch_size]},
        )
        res.raise_for_status()
        results.extend(res.json()["data"]["contactDetails"])
    return results  # [{contactId, phoneNumber, status: "created" | "updated"}]

Store the returned contactId next to your own record (or put your record ID in data, like crm_id above) so you can match webhook results later. Re-sending a contact with the same phone number updates it instead of creating a duplicate, so retries are safe. See Manage contacts for the full behavior, multiple phone numbers per contact, and validation errors.

Step 3: Start and stop the agent

# Start dialing
curl -X POST "https://api.callers.ai/agents/$AGENT_ID/start" \
  -H "Authorization: $CALLERS_API_KEY"

# Stop dialing (calls in progress finish normally)
curl -X POST "https://api.callers.ai/agents/$AGENT_ID/stop" \
  -H "Authorization: $CALLERS_API_KEY"

await fetch(`${API}/agents/${agentId}/start`, { method: "POST", headers });
await fetch(`${API}/agents/${agentId}/stop`, { method: "POST", headers });

requests.post(f"{API}/agents/{agent_id}/start", headers=HEADERS)
requests.post(f"{API}/agents/{agent_id}/stop", headers=HEADERS)

start on an active agent returns 400 Campaign already activated. and stop on a stopped agent returns 400 Campaign not activated.. Check active with GET /agents/{agentId} first, or treat those responses as success.

Stopping an agent pauses new calls. It doesn’t remove contacts or reset their attempts; starting again continues where it left off.

Step 4: Receive outcomes

Subscribe a webhook to the events you need. A typical outbound integration uses:

Event	Use it to
`CALL_FINISHED`	Log every call with duration, transcript, and recording.
`POST_PROCESSING_FINISHED:INTERESTED` (or your custom success criterion names)	Create a deal, book a follow-up, alert sales.
`POST_PROCESSING_FINISHED:DO_NOT_CALL`	Mark the person as opted out in your CRM.
`CONTACT_UNREACHED`	The contact ran out of attempts without a conversation. Hand off to another channel.

Subscribe through the dashboard or the API:

curl -X POST "https://api.callers.ai/agents/$AGENT_ID/webhook/subscribe" \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CRM sync", "url": "https://example.com/callers", "events": ["CALL_FINISHED", "POST_PROCESSING_FINISHED:INTERESTED", "POST_PROCESSING_FINISHED:DO_NOT_CALL"]}'

The API subscribe endpoint accepts the standard call events. To subscribe to CONTACT_UNREACHED, CONTACT_LAST_DAILY_ATTEMPT, or events for custom success criteria, configure the webhook in the agent’s Webhooks settings in the dashboard.

Match each payload to your record with contact.id, contact.phoneNumber, or a value you put in contact.data. See Webhook events and Webhook payload.

Step 5: Track progress

Poll sparingly; webhooks are the primary signal. For dashboards and reconciliation:

# Contact counts by status
curl "https://api.callers.ai/agents/$AGENT_ID/report" \
  -H "Authorization: $CALLERS_API_KEY"

# Interested contacts, most recent attempt first
curl -g "https://api.callers.ai/agents/$AGENT_ID/contacts?statuses[]=INTERESTED&sortAttribute=LAST_ATTEMPT&sortDirection=DESC&perPage=100" \
  -H "Authorization: $CALLERS_API_KEY"

# All calls for one contact
curl "https://api.callers.ai/agents/$AGENT_ID/contacts/$CONTACT_ID/calls" \
  -H "Authorization: $CALLERS_API_KEY"

const report = await fetch(`${API}/agents/${agentId}/report`, { headers }).then((r) => r.json());

const params = new URLSearchParams({
  "statuses[]": "INTERESTED",
  sortAttribute: "LAST_ATTEMPT",
  sortDirection: "DESC",
  perPage: "100",
});
const interested = await fetch(`${API}/agents/${agentId}/contacts?${params}`, { headers })
  .then((r) => r.json());

report = requests.get(f"{API}/agents/{agent_id}/report", headers=HEADERS).json()["data"]

interested = requests.get(
    f"{API}/agents/{agent_id}/contacts",
    headers=HEADERS,
    params={
        "statuses[]": "INTERESTED",
        "sortAttribute": "LAST_ATTEMPT",
        "sortDirection": "DESC",
        "perPage": 100,
    },
).json()["data"]

The report for an outbound agent counts contacts by status, plus call totals:

Response

{
  "status": "success",
  "data": {
    "totalCallsCount": 412,
    "contactsByStatuses": {
      "NEW": 40,
      "PENDING_RETRY": 55,
      "SCHEDULED": 3,
      "IN_PROGRESS": 2,
      "FAILED": 4,
      "UNREACHED": 21,
      "NOT_INTERESTED": 60,
      "INTERESTED": 48,
      "COMPLETED": 30,
      "SKIPPED": 5,
      "CALL_ME_LATER": 20,
      "WRONG_NUMBER": 7,
      "DO_NOT_CALL": 5
    },
    "totalContacts": 300,
    "answeredCallsCount": 187
  }
}

For an inbound agent, contactsByStatuses counts calls instead (COMPLETED, IN_PROGRESS, ANALYZING, INTERESTED, NOT_INTERESTED, FAILED) and there is no totalContacts or answeredCallsCount.

List calls

GET /agents/{agentId}/calls returns the agent’s calls as a plain array, newest first, with page and perPage (default 50):

curl "https://api.callers.ai/agents/$AGENT_ID/calls?page=0&perPage=100" \
  -H "Authorization: $CALLERS_API_KEY"

const calls = await fetch(`${API}/agents/${agentId}/calls?page=0&perPage=100`, { headers })
  .then((r) => r.json())
  .then((body) => body.data);

calls = requests.get(
    f"{API}/agents/{agent_id}/calls",
    headers=HEADERS,
    params={"page": 0, "perPage": 100},
).json()["data"]

Each call includes id, sessionId, contactId, agentId (and the legacy campaignId), status, hangUpReason, duration, createdAt, phoneFrom, phoneTo, messages, summary, goal, events, and recordingUrl when available. Keep paging until a page comes back with fewer than perPage items.

Download a call’s SIP trace

For calls placed over your own SIP trunk, GET /agents/{agentId}/calls/{callId}/pcap returns the packet capture of the SIP signaling (application/vnd.tcpdump.pcap). Share it with your carrier when you debug one-way audio or rejected calls. It’s only available for SIP calls and only for recent ones; otherwise the endpoint returns 404.

curl "https://api.callers.ai/agents/$AGENT_ID/calls/$CALL_ID/pcap" \
  -H "Authorization: $CALLERS_API_KEY" \
  -o call.pcap

import { writeFile } from "node:fs/promises";

const res = await fetch(`${API}/agents/${agentId}/calls/${callId}/pcap`, { headers });
if (!res.ok) throw new Error(`${res.status}: PCAP not available`);
await writeFile("call.pcap", Buffer.from(await res.arrayBuffer()));

res = requests.get(f"{API}/agents/{agent_id}/calls/{call_id}/pcap", headers=HEADERS)
res.raise_for_status()
with open("call.pcap", "wb") as f:
    f.write(res.content)

Step 6: Stop calling specific people

When someone converts or opts out in your system, archive them so the agent stops calling. Archived contacts are kept (with their history) and can be restored.

curl -X DELETE "https://api.callers.ai/agents/$AGENT_ID/contacts/phone-number/bulk" \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumbers": ["+14155552671", "+14155550123"], "archiveReason": "Converted in CRM"}'

await fetch(`${API}/agents/${agentId}/contacts/phone-number/bulk`, {
  method: "DELETE",
  headers,
  body: JSON.stringify({
    phoneNumbers: ["+14155552671", "+14155550123"],
    archiveReason: "Converted in CRM",
  }),
});

requests.delete(
    f"{API}/agents/{agent_id}/contacts/phone-number/bulk",
    headers=HEADERS,
    json={"phoneNumbers": ["+14155552671", "+14155550123"], "archiveReason": "Converted in CRM"},
)

Correct an outcome

If your team learns that a call’s outcome was wrong, set it from your system:

curl -X POST "https://api.callers.ai/agents/$AGENT_ID/calls/$CALL_ID/setStatus?callStatus=INTERESTED" \
  -H "Authorization: $CALLERS_API_KEY"

callStatus accepts INTERESTED, NOT_INTERESTED, VOICE_MAIL, CALL_ME_LATER, DO_NOT_CALL, WRONG_NUMBER, or COMPLETED. Pass callReachedGoal with a success criterion’s name (for example, callReachedGoal=Demo%20Scheduled) to record which criterion was met.

Backfill missed webhooks

If your endpoint was down, you don’t have to guess what you missed. List the agent’s calls, then fetch the exact webhook payload for each one with GET /agents/{agentId}/calls/{callId}/webhook-payload and run it through the same handler your webhook uses. The payload matches the final delivery (its webhookEvent is the current state of the call), so skip calls you already have by id.

Node.js

async function backfill(agentId, since, handleWebhook) {
  for (let page = 0; ; page++) {
    const calls = await fetch(`${API}/agents/${agentId}/calls?page=${page}&perPage=100`, { headers })
      .then((r) => r.json())
      .then((body) => body.data);

    for (const call of calls) {
      if (new Date(call.createdAt) < since) return; // calls are newest first
      const payload = await fetch(`${API}/agents/${agentId}/calls/${call.id}/webhook-payload`, { headers })
        .then((r) => r.json())
        .then((body) => body.data);
      await handleWebhook(payload); // same function your webhook endpoint calls
    }

    if (calls.length < 100) return;
  }
}

await backfill(agentId, new Date("2026-10-20T00:00:00Z"), handleWebhook);

Add a short delay between requests for large backfills, and don’t run this in a tight loop on a schedule: webhooks remain the primary signal.

Best practices

One agent per use case. Keep script, schedule, and success criteria specific. Use agent groups to organize many agents.
Push contacts ahead of the calling window so the agent can start dialing as soon as hours open.
Store Callers IDs. Save contactId and the call id from webhooks to make reconciliation and re-fetching easy.
Backfill from the API. If your endpoint was down, list calls with GET /agents/{agentId}/calls and fetch each payload with GET /agents/{agentId}/calls/{callId}/webhook-payload. See Backfill missed webhooks.
Test first. Run a few contacts (your own numbers) through the agent before loading a full list.

Troubleshooting

Bulk upload returns fewer added + modified than requested

Some contacts were skipped: invalid or missing phone numbers, missing name, or missing required variables. Validate numbers before sending, or use fixUSPhoneNumber=true for 10-digit US numbers without a country code.

Bulk upload is rejected with 400 and a list of data issues

At least one contact has invalid data (non-string value, invalid key, too large). Invalid data on any contact rejects the whole request; each issue includes the contact’s index in path.

The agent stopped by itself

It ran out of eligible contacts. Add more contacts and call start. Also check the agent in the dashboard for a failure reason (for example, a missing phone number).

A contact was called again after I re-uploaded it

Re-uploading updates the existing contact and keeps its status. If it had been archived, re-uploading restores it (unless you send "archived": true), and it can be called again if it still has attempts left.

Manage contacts

Validation, duplicates, filters, and archiving.

Scheduling and retries

Availability hours, retry rules, and concurrency.

Webhook events

Every event and when it fires.

Statuses and outcomes

What each call and contact status means.

Get started

Guides

Webhooks

Endpoints

Launch outbound calls

Before you begin

How outbound dialing works

Step 1: Map your data to variables

Step 2: Push contacts

Step 3: Start and stop the agent

Step 4: Receive outcomes

Step 5: Track progress

List calls

Download a call’s SIP trace

Step 6: Stop calling specific people

Correct an outcome

Backfill missed webhooks

Best practices

Troubleshooting

Manage contacts

Scheduling and retries

Webhook events

Statuses and outcomes

​Before you begin

​How outbound dialing works

​Step 1: Map your data to variables

​Step 2: Push contacts

​Step 3: Start and stop the agent

​Step 4: Receive outcomes

​Step 5: Track progress

​List calls

​Download a call’s SIP trace

​Step 6: Stop calling specific people

​Correct an outcome

​Backfill missed webhooks

​Best practices

​Troubleshooting

​Related

Manage contacts

Scheduling and retries

Webhook events

Statuses and outcomes

Before you begin

How outbound dialing works

Step 1: Map your data to variables

Step 2: Push contacts

Step 3: Start and stop the agent

Step 4: Receive outcomes

Step 5: Track progress

List calls

Download a call’s SIP trace

Step 6: Stop calling specific people

Correct an outcome

Backfill missed webhooks

Best practices

Troubleshooting

Related