Create Campaign
Campaigns
Create Campaign
Create a new campaign that ties an agent to a schedule, rate, and retry policy.
The campaign will be created in scheduled status. It starts automatically when start_timestamp is reached.
POST
Create Campaign
Overview
A campaign ties an agent to a schedule, rate, and retry policy — defining who to contact, when, and how fast. The campaign is created inscheduled status and activates automatically when start_timestamp is reached.
Cohorts can be uploaded at any point — before the campaign starts, while it’s active, or after a pause. Each new cohort is processed independently and queued for calling. Start with a small test cohort to validate your agent’s performance, then scale up by uploading larger batches.
Key constraints
start_timestampmust be at least 120 seconds from now and no more than 7 days from nowend_timestampmust be at least 120 seconds afterstart_timestampand no more than 30 days after itallowed_scheduledefines the business-hours window (timezone, days, time range) within which calls are placed — dials only happen inside this window
Typical flow
- Create a campaign with agent config, schedule, and retry policy
- Upload one or more cohorts — each is a CSV of users + transformation config
- System processes and dispatches calls at the configured rate
- Retry engine handles failures automatically
- Upload additional cohorts at any time while the campaign is running
- Campaign ends when the time window expires or you cancel it
Call Rate
attempts_per_second is the rate at which the system places outbound dials. It is a dial rate, not an answer rate — every outbound dial counts as one attempt, regardless of whether it connects.
Range: 0.1 – 500
Attempts
- Each initial outbound dial = 1 attempt
- Each retry = 1 additional attempt
- Busy, no-answer, short-duration, and connected calls all count equally
max_retries: 3 can generate up to 4 attempts total (1 initial + 3 retries).
Capacity planning
Calls are only placed within yourallowed_schedule window. Use this formula:
This is the theoretical maximum. Any time the campaign spends paused, outside the allowed schedule, or waiting between retries reduces the actual number of attempts placed.
Retry conditions
Retries are triggered based on how the previous call ended. Configure which outcomes should be retried underretry_config.retry_on:
short_duration in detail
A call is considered short-duration when the user answers but hangs up quickly — before the conversation has a meaningful chance to happen. Common causes: the user didn’t realize it was a call, accidentally answered, or the call dropped immediately after connecting.
threshold_seconds sets the cutoff. Any call that connects and lasts less than this value is treated as incomplete and queued for a retry.
1 – 1200 seconds.
Retry budget
Your effective attempt budget =cohort_size × (1 + max_retries).
If
attempts_per_second × window is less than this, some users may not complete all retries before the campaign ends.
Load balancing
If you configure multipleconnection_configs, traffic is split proportionally by weight. With weights 3 and 1, 75% of dials go through the first connection, 25% through the second. Phone numbers within each connection are used equally.
Choosing the right rate
Answer rates vary by audience and time of day. A 40–60% connect rate is typical — not every dial will become a conversation. Factor this into your cohort size and rate planning.
Example request
Key fields
End-to-end flow
-
Create the campaign —
POST /campaigns
Returnscampaign_idwithstatus: scheduled. -
Upload a cohort —
POST /campaigns/{id}/cohorts/upload
Returnscohort_idwithstatus: processing. -
Poll until processing completes —
GET /campaigns/{id}/cohorts/{cohort_id}
Wait forstatus: completedorfailed. -
Check for rejected records — if
result.rejected_records > 0, download and review:
GET /campaigns/{id}/cohorts/{cohort_id}/files?file_type=rejected_records -
Campaign activates automatically at
start_timestamp
Status transitions:scheduled→active. -
Monitor and control as needed:
GET /campaigns/{id}·PUT /campaigns/{id}/status(pause / resume / cancel)
Check for rejected records right after cohort processing completes. Rejected users will never be called — catching them early lets you fix data issues and re-upload before the campaign goes live.
Next: Upload a Cohort
After creating a campaign, upload a CSV of users to start placing calls.
Authorizations
Body
application/json
Request body for creating a new campaign. Ties an agent to a schedule, rate, and retry policy.
Example:
"Q1 Payment Reminders"
Agent configuration for the campaign
Campaign start time (ISO 8601)
Example:
"2026-04-01T09:00:00Z"
Campaign end time (ISO 8601)
Example:
"2026-04-15T18:00:00Z"
Schedule constraints for when the campaign can run
Optional campaign description. Max 150 characters.
Maximum string length:
150Response
Successful Response
Summary metadata for a campaign, returned in list responses.
Name of the resource
Example:
"Q1 Payment Reminders"
Unique identifier for the campaign
Example:
"camp-a1b2c3d4"
Current status
Available options:
ended, active, paused, scheduled, cancelled Example:
"scheduled"
ID of the agent
Example:
"payment-reminder-agent"
User who created this resource
Example:
"user@company.com"
Timestamp when the resource was created (ISO 8601)
Example:
"2026-03-28T10:00:00Z"
Timestamp when the resource was last updated (ISO 8601)
Example:
"2026-03-28T10:00:00Z"
Optional description
Example:
"Outbound reminder calls for Q1 overdue accounts"
Type of agent
Available options:
agent Example:
"agent"
Version of the agent to use
Example:
1
User who last updated this resource
Example:
"user@example.com"