Create campaign description

📢
This legacy information is part of v1, v2, or v3, which will be supported only until March 31, 2027. To avoid disruption, migrate your integration to v4 before that date. For endpoint mappings, Bearer token authentication, and scoped API key guidance, see the Migrating to v4 article in the Developer's Guide.

Please refer to the detailed API endpoint specification: Create a new campaign

What you can achieve with the Create campaign API

This API enables you to programmatically create a new outbound Dialer campaign by defining its dialing strategy, dialing parameters, Caller ID settings, redial rules, and assigned agents.

User permissions required

Create campaigns

Prerequisites

You must provide all required campaign configuration values.
Assigned agent e mail addresses must match users that exist in your contact center.
Some parameters are available only if the related feature is enabled for your contact center.

Making requests

The Create campaign API requires the Base URL (cluster_id) and the contact center API key as a bearer token in the request header.

Endpoint

POST /api/dialer/v1/campaigns

Authentication

Include the bearer token in the request header:

Authorization: Bearer YOUR_API_KEY

This is a POST request with a JSON body defining the campaign configuration.

Request body parameters

Parameter	Description	Type	Required	Notes
name	The name of the campaign.	string	Yes
strategy	The campaign strategy type.	string	Optional	Valid values: simple, predictive_ai. `predictive_ai` is available only if Dialer AI is enabled.
dialing_order	The order in which contacts are dialed for live campaigns.	string	Optional	Available only if the Dialing order feature is enabled. Valid values: disabled, oldest_first, newest_first. Default: disabled.
dial_level	The number of parallel attempts to dial a contact for one available agent.	integer	Optional
dial_level_override	Settings for overriding the dial level based on the number of active agents.	object	Optional	See Dial level override object.
max_dial_time	Maximum time in seconds to spend dialing a contact.	integer	Optional
max_wait_time	Maximum time in seconds to wait for an agent when a contact answers.	integer	Optional
max_dial_attempts	Maximum number of attempts to dial a contact.	integer	Optional
voice_message	Name of an audio file that will be played as a voice message.	string	Optional
answering_machine_detection	Whether Answering Machine Detection is enabled.	boolean	Optional
live	Whether or not the campaign type is live.	boolean	Optional
survey_enabled	Whether the contact can rate the call after the call ends.	boolean	Optional	Default: false.
local_time_settings	Time window and weekday rules for calling contacts.	object	Optional	Available only if Dialer contact local time is enabled. See Local time settings object.
caller_id_sets	Caller ID sets for the campaign.	array	Optional	See Caller ID sets array.
local_caller_id	Whether to use only Caller IDs that match the destination country or region.	boolean	Optional
redial_rules	Rules for redialing contacts based on call outcomes.	object	Optional	See Redial rules object.
assigned_agents	List of agent e mail addresses assigned to the campaign.	array	Optional	Each value must be a valid e mail address.

Dial level override object

Field	Description	Type	Required
enabled	Whether dial level override is enabled.	boolean	Optional
override_value	Dial level to use when the number of active agents drops to the threshold value.	number	Optional
active_agents_threshold	Number of active agents at which to apply the override.	integer	Optional

Local time settings object

Field	Description	Type	Required
call_from	Time of day when calls can start.	string	Optional
call_to	Time of day when calls must stop.	string	Optional
week_days	Days of the week when calls can be made.	array	Optional

Valid week_days values: Mon, Tue, Wed, Thu, Fri, Sat, Sun

Caller ID sets array

Each array element contains:

Field	Description	Type	Required
numbers	Phone numbers assigned to the Caller ID set.	array	Optional

Redial rules object

redial_rules groups rules by call outcome. Each outcome contains an array of rule objects.

Supported outcomes:

machine_answered
abandoned
no_answer
rejected
failed
busy

Each outcome array element contains:

Field	Description	Type	Required
units	Time units for the rule.	string	Optional
wait	Maximum time to wait before redialing.	integer	Optional
change_callerid	Whether to switch the Caller ID set when redialing.	boolean	Optional

Valid units values: s, m, h

Request example

{
  "method": "POST",
  "url": "https://cluster1.contact_center_name.com/api/dialer/v1/campaigns",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  "body": {
    "name": "Q4 Inbound Lead Follow up",
    "strategy": "simple",
    "dialing_order": "oldest_first",
    "dial_level": 1,
    "dial_level_override": {
      "enabled": true,
      "override_value": 1.5,
      "active_agents_threshold": 3
    },
    "max_dial_time": 60,
    "max_wait_time": 5,
    "max_dial_attempts": 3,
    "answering_machine_detection": true,
    "survey_enabled": false,
    "local_time_settings": {
      "call_from": "08:00",
      "call_to": "22:00",
      "week_days": ["Mon", "Tue", "Wed", "Thu", "Fri"]
    },
    "caller_id_sets": [
      {
        "numbers": ["100"]
      }
    ],
    "local_caller_id": false,
    "redial_rules": {
      "no_answer": [
        { "units": "s", "wait": 600, "change_callerid": true }
      ],
      "busy": [
        { "units": "m", "wait": 10, "change_callerid": false }
      ]
    },
    "assigned_agents": ["[email protected]", "[email protected]"]
  }
}

Notes:

caller_id_sets is an array. Each item contains a numbers array.

redial_rules is an object keyed by outcome. Each outcome contains an array of rule objects.

Response

A successful response returns the created campaign object, including the campaign id and the configuration values that were created.

Element	Description	Type
id	The unique identifier of the campaign.	integer
name	The name of the campaign.	string
strategy	The campaign strategy type.	string
dialing_order	The dialing order setting.	string
dial_level	Dial level value.	integer
dial_level_override	Dial level override configuration.	object
max_dial_time	Maximum dial time in seconds.	integer
max_wait_time	Maximum wait time in seconds.	integer
max_dial_attempts	Maximum dial attempts.	integer
voice_message	Voice message name.	string
answering_machine_detection	Whether Answering Machine Detection is enabled.	boolean
live	Whether or not the campaign type is live.	boolean
survey_enabled	Whether post call survey is enabled.	boolean
local_time_settings	Local time calling rules.	object
caller_id_sets	Caller ID sets.	array
local_caller_id	Whether local Caller ID selection is enabled.	boolean
redial_rules	Redial rules by outcome.	object
assigned_agents	Assigned agent e mail addresses.	array

Response sample

{
  "id": 98765,
  "name": "Q4 Inbound Lead Follow up",
  "strategy": "simple",
  "dialing_order": "oldest_first",
  "dial_level": 1,
  "dial_level_override": {
    "enabled": true,
    "override_value": 1.5,
    "active_agents_threshold": 3
  },
  "max_dial_time": 60,
  "max_wait_time": 5,
  "max_dial_attempts": 3,
  "voice_message": "Voice message (1)",
  "answering_machine_detection": true,
  "live": false,
  "survey_enabled": false,
  "local_time_settings": {
    "call_from": "08:00",
    "call_to": "22:00",
    "week_days": ["Mon", "Tue", "Wed", "Thu", "Fri"]
  },
  "caller_id_sets": [
    {
      "numbers": ["100"]
    }
  ],
  "local_caller_id": false,
  "redial_rules": {
    "no_answer": [
      { "units": "s", "wait": 600, "change_callerid": true }
    ],
    "busy": [
      { "units": "m", "wait": 10, "change_callerid": false }
    ]
  },
  "assigned_agents": ["[email protected]", "[email protected]"]
}

Errors

Code	Message	Description
401	Unauthorized	The API key specified is invalid.
403	Forbidden	No access.
422	Unprocessable Entity	Validation error. Response includes an `errors` object with details per field.

Validation error example (422)

{
  "errors": {
    "name": ["can't be blank"]
  }
}

What you can achieve with the Create campaign API

User permissions required

Prerequisites

Making requests

Endpoint

Authentication

Request body parameters

Dial level override object

Local time settings object

Caller ID sets array

Redial rules object

Request example

Response

Response sample

Errors

Validation error example (422)

See also