List campaigns 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: List campaigns

What you can achieve with the Campaigns API

Campaigns API enables you to obtain a list of campaign IDs from your contact center and add contacts to a live outbound dialer campaign.

Note: Legacy filter[...] parameters are not included in the current OpenAPI specification, so they may not appear in the generated API reference.

List Campaigns

The List campaigns method retrieves the list of all Dialer campaigns in your contact center that you have permission to view.

You can use the List Campaign method for applications such as the following:

Get a summary of all past and current Dialer campaigns
Create a picklist of all campaigns to chain them programmatically

Tip: You can obtain the ID by using the Campaigns API GET request or by looking at the Campaigns table on the Voiso Dialer campaigns page.

Prerequisites

You must have at least one campaign configured for your contact center.

Making requests

Note: The request structure has changed. You no longer have to include the hash parameter filter[{{param}}] for requests. See Making requests (legacy) below for information about the legacy parameter structure.

The List_campaigns API requires the Base URL (cluster_id) and the contact center API key. The following table lists the optional filters you can use to refine your request.

Parameter	Description	Type	Required	Notes
name	A campaign name.	string	Optional
strategy	One or more campaign strategy types.	string	Optional	Comma separated values. Valid values: simple, advanced, predictive_ai
status	One or more campaign statuses.	string	Optional	Comma separated values. Valid values: draft, active, paused, pausing, auto_paused, auto_pausing, stopping, stopped, completed, processing, import_error
method	One or more methods of uploading numbers to the campaign.	string	Optional	Comma separated values. Valid values: csv, bitrix_crm, dynamics_crm, falcon_crm, hubspot_crm, panda_crm, popcorn_crm, proftit_crm, puma_crm, salesforce_crm, zoho_crm
live	Whether or not the campaign type is live.	boolean	Optional
limit	The maximum number of campaigns to return.	integer	Optional	Used for pagination.
offset	The number of campaigns to skip before returning results.	integer	Optional	Used for pagination.

Notes:

In the YAML, strategy, status, and method explicitly support multiple values separated by commas.
The YAML does not include file_import as a valid method value. If your UI shows other values, they are not currently represented in the OpenAPI spec.

Make a request to return a list of campaigns. For example:

GET /api/dialer/v1/campaigns?name=campaign%20name&strategy=advanced&status=active&method=csv&live=false

HTTP/1.1
Host: cluster1.contact_center_name.com
Accept: application/json
Authorization: Bearer token: 63c526cqwg05ce85e8bwtbt208943f93131c9d0d1d237b7c

JSON request example:

GET /api/dialer/v1/campaigns?name=campaign%20name&strategy=advanced&status=active&method=csv&live=false&limit=25&offset=0
Host: cluster1.contact_center_name.com
Accept: application/json
Authorization: Bearer 63c526cqwg05ce85e8bwtbt208943f93131c9d0d1d237b7c

Your JSON request example can be updated to include pagination and proper boolean typing:

{
  "method": "GET",
  "url": "https://cluster1.contact_center_name.com/api/dialer/v1/campaigns",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer 63c526cqwg05ce85e8bwtbt208943f93131c9d0d1d237b7c"
  },
  "params": {
    "name": "campaign name",
    "strategy": "advanced",
    "status": "active",
    "method": "csv",
    "live": false,
    "limit": 25,
    "offset": 0
  }
}

Response

The following table describes the elements of the response.

Element	Description	Type	Notes
campaigns	Campaigns data.	array
campaigns.id	The unique identifier of the campaign.	integer
campaigns.name	The name of the campaign.	string
campaigns.status	The current status of the campaign.	string	Valid values: draft, active, paused, pausing, auto_paused, auto_pausing, stopping, stopped, completed, processing, import_error
campaigns.strategy	The campaign strategy type.	string	Valid values: simple, advanced, predictive_ai
campaigns.method	The method for uploading numbers to the campaign.	string	Valid values: csv, bitrix_crm, dynamics_crm, falcon_crm, hubspot_crm, panda_crm, popcorn_crm, proftit_crm, puma_crm, salesforce_crm, zoho_crm
campaigns.live	Whether or not the campaign type is live.	boolean
campaigns.created_at	The date and time the campaign was created.	string	ISO 8601 date time
metadata	Information about the request settings and response content.	object
metadata.total	The total number of campaigns.	integer
metadata.limit	The maximum number of campaigns returned.	integer
metadata.offset	The number of campaigns skipped before returning results.	integer

Response sample

{
  "campaigns": [
    {
      "id": 25735,
      "name": "Canada Campaign",
      "status": "paused",
      "strategy": "simple",
      "method": "csv",
      "live": true,
      "created_at": "2023-10-20T13:06:09.310178+00:00"
    },
    {
      "id": 25473,
      "name": "Wasson Campaign October",
      "status": "completed",
      "strategy": "simple",
      "method": "hubspot_crm",
      "live": false,
      "created_at": "2023-10-03T13:33:28.746311+00:00"
    }
  ],
  "metadata": {
    "limit": 25,
    "offset": 0,
    "total": 2
  }
}

Making requests (legacy)

Earlier versions of this endpoint used the following parameter convention. This remains supported for customers who already leverage this endpoint.

Parameter	Description	Type	Required	Notes
filter[name]	A campaign name	string	Optional
filter[strategy]	A campaign strategy type	string	Optional	Valid values are: simple, advanced, and predictive_ai
filter[status]	The current status of the campaign	string	Optional	Valid values are: draft, active, paused, stopping, completed, processing, stopped, auto_paused, pausing, auto_pausing, import_error
filter[method]	The method of uploading numbers to the campaign	string	Optional	Valid values are: csv, bitrix_crm, dynamics_crm, falcon_crm, hubspot_crm, panda_crm, popcorn_crm, proftit_crm, puma_crm, salesforce_crm, and zoho_crm
filter[live]	Whether or not the campaign type is `live`	Boolean	Optional

Make a request to return a list of campaigns. For example:

GET /api/dialer/v1/campaigns?filter[name]=campaign%20name&filter[strategy]=advanced&filter[status]=active&filter[method]=csv&filter[live]=false

HTTP/1.1
Host: cluster1.contact_center_name.com
Accept: application/json
Authorization: Bearer token: 63c526cqwg05ce85e8bwtbt208943f93131c9d0d1d237b7c

JSON request example:

{
  "method": "GET",
  "url": "https://cluster1.contact_center_name.com/api/dialer/v1/campaigns",
  "headers": {
    "Accept": "application/json",
    "Authorization": "Bearer 63c526cqwg05ce85e8bwtbt208943f93131c9d0d1d237b7c"
  },
  "params": {
    "filter[name]": "campaign name",
    "filter[strategy]": "advanced",
    "filter[status]": "active",
    "filter[method]": "csv",
    "filter[live]": "false"
  }
}

Troubleshooting

The following issues are sometimes encountered:

The API key specified is invalid

The List campaigns API uses the contact center API key to validate the request. If you see this error, "error": "Invalid API key", check that you are using the correct contact center API key. For more information about API keys, refer to Authentication.