Create campaign description

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.
You can preconfigure campaign settings, including naming, Dialer type, time restrictions, retry behavior, and so on, allowing automated campaign creation from external tools or internal systems based on business logic.

User permissions required

Create campaigns

Prerequisites

You must provide all required campaign configuration values.
Team and agent names must match those that exist in your contact center.
Time values must follow the required format (see individual field notes).
The user associated with the API key must have permission to create campaigns.

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.

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

Request body parameters

Parameter	Description	Type	Required	Notes
name	The name of the new campaign.	string	Yes	Must be unique within your contact center.
campaign_type	Type of campaign.	string	Yes	Use `"live"` for API-based campaigns.
timezone	Time zone used to evaluate contact time ranges.	string	Yes	Format: IANA time zone, e.g. `"America/New_York"`
start_hour	Allowed starting hour for calls.	string	No	Format: `"HH:MM"`
end_hour	Allowed ending hour for calls.	string	No	Format: `"HH:MM"`
retry_attempts	Number of retry attempts for failed calls.	integer	No	Optional — must be 0 or greater.
retry_interval	Minutes to wait between retries.	integer	No	Optional — must be 0 or greater.
agents	List of agent sign-in email addresses to assign to the campaign.	array	No	Must match existing agent sign-in emails.
teams	List of team names to assign to the campaign.	array	No	Must match existing team names.
caller_id_group_id	ID of the Caller ID group to use.	integer	No	Refer to the Caller ID settings in the Admin Panel.

Request example

POST {
  "method": "POST",
  "url": "https://cluster1.voiso.com/api/dialer/v1/campaigns",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  "body": {
    "name": "Q4 Inbound Lead Follow-up",
    "campaign_type": "live",
    "timezone": "America/New_York",
    "start_hour": "09:00",
    "end_hour": "18:00",
    "retry_attempts": 3,
    "retry_interval": 10,
    "agents": ["[email protected]", "[email protected]"],
    "teams": ["NorthEastTeam"],
    "caller_id_group_id": 42
  }
}

Response

A successful response returns details of the newly created campaign.

Element	Description	Type
id	ID of the newly created campaign.	integer
name	Name of the campaign.	string
campaign_type	Type of the campaign.	string
status	Current status of the campaign.	string
agents	Assigned agents.	array
teams	Assigned teams.	array

Response sample

{
  "id": 98765,
  "name": "Q4 Inbound Lead Follow-up",
  "campaign_type": "live",
  "status": "draft",
  "agents": ["[email protected]", "[email protected]"],
  "teams": ["NorthEastTeam"]
}

Troubleshooting

Invalid Key

If you receive "error": "Invalid Key", ensure your API token is correct and active. Refer to Authentication.

Missing or duplicate name

If no name is provided or the name already exists:

{
  "error": "Campaign name must be unique"
}

Invalid time or timezone format

If time or timezone values are improperly formatted, the request may fail with:

{
  "error": "Invalid time or timezone format"
}

Agent or team not found

If assigned agents or teams don’t exist:

{
  "error": "Some agents or teams not found"
}

Use List agents and List teams to confirm valid entries.