Skip to navigation
API referenceCampaigns

Create campaign

Create an outbound campaign that calls or messages each recipient with the agent, within the policy’s calling windows, retrying and following up as it allows. Returns 201 for a new campaign. A repeated request, matched by idempotency_key or else by its body, returns the existing campaign with created false.

Headers

xi-api-keystringOptional

Request

This endpoint expects an object.
call_namestringRequired1-256 characters
The campaign's name.
agent_idstringRequired1-256 characters
The agent that places the calls.
recipientslist of objectsRequired
Who to call. Each recipient becomes a lead of the campaign.
channel_configobjectRequired
scheduled_time_unixintegerOptional>=0

When to start calling; omit to start now. Calls still wait for the next calling window.

timezonestringOptional
IANA timezone to read the calling windows in, overriding the policy's.
branch_idstringOptional<=256 characters
The agent branch to call with.
environmentstringOptional<=256 characters
The environment to resolve the agent's environment variables in.
target_concurrency_limitintegerOptional>=1
The most calls to place at once.
idempotency_keystringOptional1-256 characters

Makes the request safe to retry: a repeat with the same key returns the campaign it created.

outcomeobjectOptional
The result that counts as success for the campaign's calls.
policyobjectOptional

Policy to snapshot onto the campaign. When set, it wins over the workspace default and any per-agent override; when omitted, the workspace configuration must exist and supplies the policy.

variantenumOptional

simple runs one attempt per recipient with always-on calling windows and nothing collected, and cannot be combined with policy. advanced uses policy or the workspace configuration, and is the default for phone campaigns.

Allowed values:

Response

Successful Response
campaignobject
createdboolean
False when the request repeated an earlier one and returned its campaign.
within_calling_windowboolean
Whether calling starts right away rather than at the next calling window.

Errors

422
Outbound Campaigns Create Request Unprocessable Entity Error