Skip to main content
POST
Create a campaign

Authorizations

Authorization
string
header
required

API key (fam_..., created under Settings → API Keys) or an OAuth 2.0 access token (fam_at_...). REST operations also require API Access for the credential's workspace. Keys can be restricted to scopes such as assistants:read, calls:write, campaigns:write, automations:read, dashboards:read, dashboards:write, leads:write, segments:write, loop:read, loop:write, phone_numbers:write, sip_trunks:write, knowledge:write, voices:read, billing:read, billing:write, settings:write, platform:read, platform:write; a *:write scope implies the matching *:read. Automation and dashboard endpoints also accept the legacy calls:* scope. Keys without scope restrictions have full access within the workspace's available capabilities.

Body

application/json
name
string
required
assistant_id
string<uuid> | null

Assistant that runs the calls. Must belong to your workspace.

channel
enum<string>
Available options:
phone_call,
whatsapp_template,
whatsapp_call,
sms
channel_config
object

Sender and message of the channel. sms: from_number_id (a workspace number) or rcs_sender_id (a company name, RCS), exactly one, plus message and variable_mapping. whatsapp_template: connector_id, template_id, variable_mapping.

follow_up_config
object

Optional voice follow-up after retries are exhausted. channel is off | whatsapp_template | sms | email. An sms follow-up names its sender with exactly one of from_number_id (a workspace number) or rcs_sender_id (a company name, RCS). Email is follow-up only and uses subject, message, and variable_mapping; it sends from the campaign assistant address. A campaign with a sequence takes no follow-up: any channel other than off is rejected with 400 (use message steps in the sequence instead), also when the request adds a sequence to a campaign whose stored follow-up is on and does not turn it off.

scheduled_start_at
string<date-time> | null
concurrency
integer

Maximum parallel voice calls for this campaign. Must fit the workspace's effective Concurrent Lines allowance, including add-ons. Calls across campaigns share that workspace allowance.

Required range: 1 <= x <= 2147483647
retry_max
integer

Max retry attempts per lead. Ignored when sequence is set.

Required range: x >= 0
retry_delay_minutes
integer

Minutes between retries. Ignored when sequence is set.

Required range: x >= 1
calling_windows
object

Allowed calling windows per weekday, local to the campaign timezone. Keys: mon–sun; each value is an array of ["HH:MM", "HH:MM"] start/end pairs (24h). An empty array or missing key blocks the whole day.

timezone
string

IANA timezone, e.g. Europe/Berlin.

amd_enabled
boolean
voicemail_action
enum<string>
Available options:
hangup,
drop_message
voicemail_message
string | null

Required when voicemail_action is drop_message.

amd_mode
enum<string>

Answering-machine detection sensitivity when AMD is enabled.

Available options:
conservative,
aggressive
ivr_navigation
boolean

Allow navigating phone menus. Enabling requires workspace Beta features.

external_audience
object | null

Opt-in external beta audience. Phone calls only with follow-up off. Null selects existing local leads. Current membership, scenario and explicit voice permission are checked before every attempt; no profile mirror. Cannot change after execution starts.

retry_on_voicemail
boolean

Retry leads whose call reached a voicemail or an unavailable mailbox, within retry_max. When false, a completed call counts as reached even if a voicemail answered. Ignored when sequence is set.

retry_until_goal
boolean

Mark a lead completed only when goal_variable evaluates to true after the call; otherwise schedule another attempt, within retry_max. Ignored when sequence is set.

goal_variable
string | null

Yes/no post-call analysis field of the assistant, or the built-in success result, that decides whether a lead's goal was reached. Used by retry_until_goal and by the conversion count of classic campaigns. null clears it. Retries ignore it when sequence is set.

mark_complete_when_no_leads
boolean

Mark the campaign completed automatically when no lead is left to call. When false, the campaign stays open for leads added later.

outbound_ringing_timeout_sec
integer | null

Seconds an outbound call may ring before it counts as unanswered (15 to 80). null uses the platform default.

Required range: 15 <= x <= 80
sequence
object | null

Sequence of call and message steps with outcomes and per-step attempts. null keeps the classic retry settings (retry_max, retry_delay_minutes). Campaigns created without it stay classic. Phone call campaigns only; not with an external audience. Draft and paused campaigns can change it, also after they were started (see updateCampaign); a running campaign is paused first, a scheduled one cancels its schedule first, a completed one is duplicated.

Example:
number_pool
object | null

Caller numbers to dial from. null uses the assistant's outbound number. Needs a sequence (400 without one); phone call campaigns only; not with an external audience. Removing the sequence resets it to null.

contact_timezone_mode
enum<string>
default:campaign

Which time zone the calling windows follow. campaign: the campaign's timezone. contact: each contact's own local time, derived from the phone number; needs a sequence (400 without one), because only sequence campaigns apply it.

Available options:
campaign,
contact
holidays
object

Days without calls. Defaults to no public holidays and no custom dates. Non-default values need a sequence (400 without one), because only sequence campaigns apply them.

double_dial
boolean
default:false

Redial once immediately when a call ends unanswered or busy. Off by default; true needs a sequence (400 without one), because only sequence campaigns redial; repeated immediate calls can be an unreasonable nuisance under EU law, so check the countries you call before turning it on.

Response

The created campaign.

data
object
required