Campaign Management

What Are Campaigns?

A campaign is either outbound (we dial leads from a list) or inbound (a phone number routes its calls here). Set direction at creation; it defaults to outbound and can only change while the campaign is draft. Outbound fits appointment reminders, order follow-ups, renewals and lead qualification for contacts who consented. Inbound campaigns answer on an attached number only while running. In any other status the number declines callers. See Inbound Calls.

Queue Management

Large lead lists, with running campaigns sharing your account’s per-minute limit.

Dispatch Hours

Dial only inside the hours and weekdays you set, in the campaign’s time zone.

Retries

Call back after a busy line, no answer, a failed dial or voicemail, on your schedule.

Stats

Answered, completed, converted and failed counts on request.

How Campaigns Work

1. Create

Use the dashboard or POST /v1/campaigns to set instructions, voice and schedule. A new campaign is draft.

2. Add Leads

Upload a CSV in the dashboard or use the leads endpoints. Each lead can carry its own variables, like {{name}} or {{order_number}}. Make sure you have consent where the law requires it.

3. Start

POST /v1/campaigns/{id}/start. Outbound needs at least one lead (else 400) and available credit covering one call’s full max_duration, 10 minutes if the campaign sets none (else 402). With a future schedule_time the campaign goes scheduled and starts itself at that time. Inbound start just sets running and creates no run.

4. Dialling

Calls go out within the account’s per-minute limit, the campaign’s max_parallel_calls, your concurrent-call slots, the dispatch hours and the retry schedule. A lead whose number your account can’t call ends failed with the reason in error_message, isn’t retried and doesn’t count toward an automatic pause.

5. Monitoring

GET /v1/campaigns/{id}/stats returns answered, completed, converted and failed counts, total talk time and the current run.

6. Stopping

A campaign never completes by itself. Once its leads run out it stays running and dials any lead you add later. POST /v1/campaigns/{id}/stop ends it (completed) and cancels its queued calls.

Campaign Statuses

Status	Meaning	Next
`draft`	Created, never started. Outbound doesn’t dial; inbound doesn’t answer	Edit, Start
`scheduled`	Started with a future `schedule_time`, waiting for it	Edit, Stop
`running`	Outbound dials; inbound answers	Pause, Stop
`paused`	Paused by you, or automatically with a `pause_reason`. Inbound declines new callers	Resume, Stop
`completed`	Stopped with `/stop`	Start (opens a new run)
`cancelled`	Cancelled when the account was closed or suspended	Start (opens a new run)

Start works from any status unless a run is already active (409). Resume needs paused and the same credit as start. Stop works from any status.

Caller ID

An outbound campaign calls from config.from_number, or from a random number in config.phone_number_ids when from_number isn’t set. from_number must be an active or verified number on your account: otherwise create or update fails with 422 (from_number_not_owned) and nothing is saved. It’s checked again on every test call and each time the campaign queues calls. If the number stops qualifying, test calls get the same 422 and a running campaign pauses with pause_reason: phone_number_deleted.

API Endpoints

Endpoint	Description
`GET /v1/campaigns`	List campaigns. Filter with `?direction=inbound` or `?direction=outbound`
`GET /v1/campaigns/{id}`	Get campaign details (`direction`, `inbound_phone_numbers`)
`GET /v1/campaigns/{id}/stats`	Call counters and the current run
`POST /v1/campaigns`	Create. Pass `direction: inbound` for an answering campaign
`PATCH /v1/campaigns/{id}`	Update the name, schedule, dispatch hours or `config`
`POST /v1/campaigns/{id}/start`	Outbound: start dialling. Inbound: start answering on the attached number
`POST /v1/campaigns/{id}/pause`	Outbound: stop dialling. Inbound: stop answering
`POST /v1/campaigns/{id}/resume`	Outbound: start dialling again. Inbound: start answering again
`POST /v1/campaigns/{id}/stop`	End the campaign (`completed`) and cancel its queued calls
`POST /v1/campaigns/{id}/test`	Place one real call with the campaign’s config. Billed like any call, needs the same credit as start, and isn’t counted in the campaign’s stats
`PATCH /v1/phone-numbers/{id}`	Attach or detach the inbound number

max_calls_per_minute (default 20) caps how many calls POST /v1/calls places per minute. It’s also the per-minute budget running campaigns share. Each campaign asks for up to its max_parallel_calls per minute (default 10). When the total asked is over the account limit, every campaign is scaled down in proportion. A campaign asking for less never holds capacity it won’t use. Example: limit 20, campaign A asks 10, campaign B asks 30. Total 40 is twice the limit, so A gets 5 and B gets 15.

Timezone & Business Hours

Calls go out only inside the dispatch window, in the campaign’s timezone (UTC when unset). dispatch_hours_start and dispatch_hours_end set the default window, dispatch_weekdays the days (1 is Monday, 7 is Sunday). dispatch_hours_overrides gives one day its own windows; an empty list makes it a day off.

{
  "name": "Appointment reminders",
  "timezone": "America/New_York",
  "dispatch_hours_start": "09:00",
  "dispatch_hours_end": "17:00",
  "dispatch_weekdays": [1, 2, 3, 4, 5],
  "dispatch_hours_overrides": {
    "5": [{ "start": "09:00", "end": "13:00" }]
  }
}

You’re responsible for following local calling laws (TCPA/TSR/DNC, GDPR). TopCalls doesn’t keep a do-not-call list: remove leads who opt out.

Retry Logic

A lead is called again only after a no-contact outcome: busy, no answer, a failed dial, or voicemail. Once a call to that number reaches a person, it isn’t retried in that run. Retries stop at max_attempts_per_lead (1 to 10). The retry schedule has one slot per retry, used in order:

A delay: “wait 30 minutes” after the previous attempt. Skipped if it lands outside the schedule’s retry hours
A fixed time: “6:00 PM, two days after the first call”, in the campaign’s time zone. Skipped if it’s already past

When no slot is left, the lead is done. Dispatch hours still apply. Set the schedule in the campaign editor.

Lead Variables

Each lead’s fields fill the matching variables:

{
  "phone_number": "+14155551234",
  "name": "John Smith",
  "appointment_date": "2025-12-24",
  "appointment_time": "3:00 PM"
}

Use in instructions:

You are calling {{name}} about their appointment on {{appointment_date}}
at {{appointment_time}}.

Bot Protection

Legacy only, and on by default. When the other side behaves like an automated system (scripted lines, the same non-answer to different questions), the call ends so it doesn’t burn credit. Turn it off in the campaign editor or with bot_protection_enabled: false. Live has no bot protection and rejects bot_protection_enabled: true.

Voicemail Detection

Calls hang up when they reach an answering machine or voicemail, in any language, so a mailbox greeting doesn’t run up the bill. A voicemail outcome counts as no contact, so the lead can be retried.

Campaign Stats

GET /v1/campaigns/{id}/stats counts the campaign’s calls when you ask. Test calls aren’t included.

Field	Description
`contacted_count`	Calls that were answered
`completed_count`	Calls with status `completed`
`success_count`	Calls whose disposition matches a conversion outcome, ignoring case
`failure_count`	Calls with status `failed`
`total_duration_seconds`	Talk time across all calls
`current_run`	The latest run (status, start and pause times, leads processed), or `null` if never started

Best Practices

Get consent wherever the law requires it, and remove leads who ask not to be called.
Start with 10 to 20 leads and read the transcripts before you scale.
Give every campaign dispatch hours and a time zone.
Keep max_attempts_per_lead low enough that nobody gets called all week.
Watch the connect rate, then move hours or retries if it drops.

Getting Started

Core Concepts

Guides

Use Cases

Integrations

What Are Campaigns?

Queue Management

Dispatch Hours

Retries

Stats

How Campaigns Work

Campaign Statuses

Caller ID

API Endpoints

Timezone & Business Hours

Retry Logic

Lead Variables

Bot Protection

Voicemail Detection

Campaign Stats

Best Practices

Next Steps

Making Calls Guide

Webhooks Guide

​What Are Campaigns?

Queue Management

Dispatch Hours

Retries

Stats

​How Campaigns Work

​Campaign Statuses

​Caller ID

​API Endpoints

​Rate Limiting & Fair Share

​Timezone & Business Hours

​Retry Logic

​Lead Variables

​Bot Protection

​Voicemail Detection

​Campaign Stats

​Best Practices

​Next Steps

Making Calls Guide

Webhooks Guide

What Are Campaigns?

How Campaigns Work

Campaign Statuses

Caller ID

API Endpoints

Rate Limiting & Fair Share

Timezone & Business Hours

Retry Logic

Lead Variables

Bot Protection

Voicemail Detection

Campaign Stats

Best Practices

Next Steps