Campaign Lists
This guide describes the APIs available to automatically manage Engage campaign lists. Using these APIs you can:
Overview
Lists determine who receives your campaign. Engage campaign lists can be manually managed through the Engage menu option at the top of the CPaaS Portal or the Engage application within the Customer Portal, but you can also automate campaign lists through our APIs.
Note: These APIs are specific to lists used within Engage. For information about SmartFlows lists, check out the List Management APIs page.
Getting Started
Before you begin using these APIs make sure you've obtained an authentication token, and check out the API Basics page to learn more about basic requirements for using the APIs.
Note: For all requests, Content-Type and Accept headers must be in JSON format.
Base URL
All of the following endpoints share the same base URL:
https://engage.intelepeer.com
(e.g., GET/https://engage.intelepeer.com/_rest/v2/lists).
Campaign Lists APIs
Click on the APIs below to view the parameters and code samples associated with each endpoint.

Use this endpoint to enumerate all of your lists in Engage.
Note: This is specific to lists used within Engage. For information about SmartFlows lists, check out the List Management APIs page.
Endpoint
GET /_rest/v2/lists
Sample Responses
Code 200 Response
Response code 200 returns a collection of list objects.
{
"lists": [
{
"customerId": "1028811",
"listName": "Engage List",
"description": "This is a list description. EX:Customer Conacts, Product Info, General Notes ",
"sharing": "public",
"deleteFlag": false,
"modifiedDate": "2022-02-22T16:55:46.443Z",
"modifiedBy": "*",
"createdDate": "2022-02-22T14:40:19.813Z",
"createdBy": "*",
"listId": "6214f5d34b99a300098407ea",
"headerInfo": [
"firstname",
"lastname"
],
"status": "completed"
},
{
"customerId": "1028811",
"listName": "default_trans_list",
"description": "default fields for flows requiring manual transcription.",
"sharing": "private",
"deleteFlag": false,
"modifiedDate": "2021-12-09T17:07:21.000Z",
"modifiedBy": "erusch",
"createdDate": "2021-12-09T17:32:20.883Z",
"createdBy": "erusch",
"listId": "61b23da45a16800008b67c91",
"headerInfo": [
"session_id",
"ANI",
"DNIS",
"start_datetime",
"end_datetime",
"first_name",
"last_name",
"address1",
"address2",
"city",
"state",
"zip",
"to_trans",
"trans_datetime",
"send_datetime",
"last_update"
],
"status": "created"
},
{
"customerId": "1028811",
"listName": "health survey 2",
"description": null,
"sharing": "private",
"deleteFlag": false,
"modifiedDate": "2021-11-04T16:01:07.000Z",
"modifiedBy": "abaro",
"createdDate": "2021-11-04T17:50:05.999Z",
"createdBy": "abaro",
"listId": "61841d4dd2fde900092aff70",
"headerInfo": [
"res1",
"res2",
"res3",
"res4",
"res5",
"number",
"extra1",
"extra2",
"extra3",
"timelog"
],
"status": "created"
}
]
}
Code 401 Response
Response code 401 returns an error that the authorization token is invalid.
{
"message": "string",
"status": 401
}
Code 500 Response
Response code 500 returns an error during the retrieval of lists.
{
"message": "Something went wrong during the retrieval of a customer's lists",
"status": 500
}

Use this endpoint to get details on a particular list in Engage.
Endpoint
GET /_rest/v2/lists
Parameters
Note: Either the "Id" or "Name" parameter is required. The response will include different details depending on which parameter you use (see response examples below).
-
Id:
-
Key = id; Value = campaignId
Note: Use this parameter to retrieve the Contact IDs (show in the "contactRel" section).
-
-
Name:
-
Key = name; Value = campaignName
-
Sample Request
Example with Id:
GET /_rest/v2/lists?id=5f7ca4beb854df0ac6b8bee1
Example with Name:
GET /_rest/v2/lists?id=My List
Note: Your query must include at least four characters and spaces are allowed.
Sample Responses
Code 200 Response
Response code 200 returns a list object when a list was successfully created.
Example with Id:
{
"listName": "Engage List",
"description": "This is a list description. EX:Customer Conacts, Product Info, General Notes ",
"modifiedDate": "2022-02-22T16:55:46.443Z",
"modifiedBy": "*",
"createdDate": "2022-02-22T14:40:19.813Z",
"createdBy": "*",
"deleteFlag": false,
"customerId": "1028811",
"campaignRel": [],
"contactRel": [
"62151592c35e1400093c7e1f",
"62151592c35e1400093c7e1e"
],
"_id": "6214f5d34b99a300098407ea",
"autoDetectTZ": null,
"state": 0,
"location": "US",
"headerInfo": {
"headers": [
"firstname",
"lastname"
],
"moc": null
}
}
Example with Name:
[
{
"customerId": "1028811",
"listName": "Engage List",
"description": "This is a list description. EX:Customer Conacts, Product Info, General Notes ",
"deleteFlag": false,
"modifiedDate": "2022-02-22T16:55:46.443Z",
"modifiedBy": "*",
"createdDate": "2022-02-22T14:40:19.813Z",
"createdBy": "*",
"status": "completed",
"autoDetectTZ": null,
"state": 0,
"location": "US",
"headerInfo": {
"headers": [
"firstname",
"lastname"
],
"moc": null
},
"_id": "6214f5d34b99a300098407ea"
}
]
Code 401 Response
Response code 401 returns an error that the authorization token is invalid.
{
"message": "string",
"status": 401
}
Code 404 Response
Response code 404 returns a message that the campaign id or name is wrong and the campaign is not found.
Code 422 Response
Response code 422 returns a message that the name parameter was less than four characters and the list details could not be retrieved.
Code 500 Response
Response code 500 returns an error when trying to retrieve list details.
{
"message": "Something went wrong when trying to get list details",
"status": 500
}

Use this endpoint to create and save a new list in Engage.
Endpoint
POST /_rest/v2/lists
Note: You must send your request in JSON format.
Body
Required field:
-
listName
Optional field:
-
listDescription
Note: Any other fields in the body are ignored.
Sample Request
{
"listName": "Engage List",
"listDescription": "This is a list description. EX:Customer Conacts, Product Info, General Notes",
"headers": ["firstname", "lastname"]
}
Sample Responses
Code 201 Response
Response code 201 returns a list object upon successfully creating a list.
{
"listName": "Engage List",
"description": "This is a list description. EX:Customer Conacts, Product Info, General Notes",
"modifiedDate": "2022-02-22T13:56:13.000Z",
"modifiedBy": "*",
"createdDate": "2022-02-22T14:40:19.813Z",
"createdBy": "*",
"customerId": "1028811",
"contactRel": [],
"campaignRel": [],
"deleteFlag": false,
"_id": "6214f5d34b99a300098407ea",
"state": 0,
"location": "US",
"headerInfo": {
"headers": [
"firstname",
"lastname"
],
"moc": null
}
}
Code 401 Response
Response code 401 returns an error that the authorization token is invalid.
{
"message": "string",
"status": 401
}
Code 422 Response
Response code 422 returns a message that the listName parameter is required.
{
"message": "The 'listName' parameter is required",
"status": 422
}
Code 500 Response
Response code 500 returns an error during list creation.
{
"message": "Something went wrong during list creation",
"status": 500
}

Use this endpoint to link a list to a campaign in Engage.
Endpoint
POST /_rest/v2/campaigns/:id/action
Note: You must send your request in JSON format.
Parameters
-
Campaign Id
Body
Required fields:
-
action
-
selectedLists: array (valid list ids)
Optional fields:
-
moc
-
The method of contact for your recipients, matching a list header (e.g., "phone").
-
-
autoDetectTZ: true or false
-
Auto detect the timezone for your recipients. If true, recipients are contacted at the appropriate local time (based on area code).
-
Sample Request
{
"action": "associate",
"selectedLists": ["51i8c0edotame81bb4cbf000"],
"moc": "phone",
"autoDetectTZ": "true"
}
Sample Responses
Code 200 Response
Response code 200 returns a boolean value of true indicating that the list was associated to your campaign.
true
Code 401 Response
Response code 401 returns an error that the authorization token is invalid.
{
"message": "string",
"status": 401
}
Code 404 Response
Response code 404 returns a message that the campaign id parameter is incorrect.
Code 422 Response
Response code 422 returns a message that the list id (selectedLists array) or action is missing, empty or invalid.
Code 500 Response
Response code 500 returns an error when trying to run the campaign.
{
"message": "Something went wrong when trying to run the campaign",
"status": 500
}

Use this endpoint to remove a list in Engage.
Endpoint
DELETE /_rest/v2/lists/:id
Note: If the list you want to delete is associated with an active campaign, you need to deactivate the campaign or remove the list from the active campaign before you can delete it.
Parameters
-
List Id
Sample Request
DELETE /_rest/v2/lists/5e9efaf957e69e652e9c1ae0
Sample Responses
Code 202 Response
Response code 202 returns a boolean value of true indicating that the list is in the process of deleting or has been deleted.
true
Code 401 Response
Response code 401 returns an error that the authorization token is invalid.
{
"message": "string",
"status": 401
}
Code 404 Response
Response code 404 returns a message that the list id parameter is incorrect.
{
"message": "The 'list id' parameter is incorrect",
"status": 404
}
Code 500 Response
Response code 500 returns an error when trying to delete the list.
{
"message": "Something went wrong when trying to delete the list",
"status": 500
}