Campaign Lists

This guide describes the APIs available to automatically manage Engage campaign lists. Using these APIs you can:

Enumerate all of your lists within Engage
Retrieve list details
Create a list

Associate a list
Delete a list

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.

List Management

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.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
{
    "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.

Copy

1
2
3
4
{
"message": "string",
"status": 401
}

Code 500 Response

Response code 500 returns an error during the retrieval of lists.

Copy

1
2
3
4
{
"message": "Something went wrong during the retrieval of a customer's lists",
"status": 500
}

Retrieve List Details

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:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{
    "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:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
[
    {
        "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.

Copy

1
2
3
4
{
"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.

Copy

1
2
3
4
{
"message": "Something went wrong when trying to get list details",
"status": 500
}

Create a List

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

Copy

1
2
3
4
5
{
    "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.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "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.

Copy

{
"message": "string",
"status": 401
}

Code 422 Response

Response code 422 returns a message that the listName parameter is required.

Copy

1
2
3
4
{
"message": "The 'listName' parameter is required",
"status": 422
}

Code 500 Response

Response code 500 returns an error during list creation.

Copy

1
2
3
4
{
"message": "Something went wrong during list creation",
"status": 500
}

Associate a List

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

Copy

1
2
3
4
5
6
{
“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.

Copy

1
true

Code 401 Response

Response code 401 returns an error that the authorization token is invalid.

Copy

{
"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.

Copy

1
2
3
4
{
"message": "Something went wrong when trying to run the campaign",
"status": 500
}

Delete a List

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.

Copy

1
true

Code 401 Response

Response code 401 returns an error that the authorization token is invalid.

Copy

{
"message": "string",
"status": 401
}

Code 404 Response

Response code 404 returns a message that the list id parameter is incorrect.

Copy

{
"message": "The 'list id' parameter is incorrect",
"status": 404
}

Code 500 Response

Response code 500 returns an error when trying to delete the list.

Copy

{
"message": "Something went wrong when trying to delete the list",
"status": 500
}