Skip to main content
POST
Create a campaign. The CSV is parsed and stored as recipients in this request. Invalid numbers and do-not-call numbers are stored as skipped recipients. Duplicate numbers are dropped. A campaign with start: "now" starts dialing on the next scheduler tick. A future start makes it scheduled. Check the file first with Preview campaign recipients. For the rules, see Outbound campaigns.

Request

Headers

string
required
Bearer token with your API key (scope agents)
string
required
application/json
string
1 to 128 printable characters with no spaces. Send the same key and the same body to retry safely. The retry gets the first campaign back with 200. The same key with a different body returns 409 IDEMPOTENCY_CONFLICT

Body

string
required
1 to 120 characters
string
required
The agent id. The agent must be in your workspace
string
required
The phone line id to call from. The line must be ready to place calls
string
required
An IANA time zone name, for example Asia/Kolkata. It sets the calling windows only
string
default:"now"
"now", or an ISO 8601 time with an offset or Z that is in the future, for example 2026-12-01T09:00:00+05:30. A time without an offset is refused
object[]
1 to 20 windows. Each is { "days": [1, ...], "start": "HH:MM", "end": "HH:MM" }. days are ISO weekdays: 1 is Monday, 7 is Sunday. end may be 24:00. A window cannot cross midnight. Default: every day, 09:00 to 20:00, in timezone. Nothing dials outside a window
integer
How many calls run at once. On a 60db Dialer line this is always 3, and any value you send is ignored. On your own line (byo), send 1 to 50. Default 3. The workspace limit also applies. See Concurrency
integer
default:"3"
1 to 30. Total calls to each recipient, including the first call
integer
default:"1800"
0 to 604800 (7 days). Wait before the next attempt. A retry that falls outside the calling windows waits for the next window to open
integer | null
default:"null"
1 to 1000, or null for no limit. The campaign pauses after this many calls in a row that did not connect
string
required
The recipient CSV as text. Up to 5 MB and 20,000 rows. It needs a phone column. See CSV format
object
default:"{}"
Maps an agent variable to a CSV column, as { "agent_variable": "csv_column" }. Both are lowercase keys. The column must exist in the CSV
object
default:"{}"
Fallback text for an agent variable, as { "agent_variable": "text" }. Up to 500 characters each. Used when the row has no value

Response

201 Created with the campaign. 200 OK with the first campaign when the Idempotency-Key and body match an earlier request. The response has the same fields as Get campaign, with status set to running or scheduled.

Errors

CAMPAIGN_INVALID covers these cases:
  • The CSV has no phone column, has a duplicate header, has more than 20,000 rows, is larger than 5 MB, or cannot be parsed. field is csv_text.
  • No row can be called after the do-not-call check. field is csv_text.
  • start is not in the future. field is start.
  • concurrency_limit is outside 1 to 50 on your own line. field is concurrency_limit.
  • variable_mapping or variable_defaults has a bad key or value, or maps to a column the CSV does not have. field is variable_mapping or variable_defaults.

Example