Lists
The Lists resource has full CRUD functionality. It allows you to Create, Retrieve, Update, and Delete Lists. The following actions can be performed on this resource...
Retrieve All Lists
Retrieves all lists associated with a specific brand.
You can include additional parameters in the request as described in the Query Parameters section. For instance, the request below will return only lists with the name "Join".
Example Response:
{
"data": [
{
"contact_list_id": 2222,
"_brand_id": 123456789,
"name": "Join",
"description": "Join the VIP list",
"created": "2024-01-01 15:36:40"
}
],
"pagingData": {
"prevPage": null,
"currentPage": null,
"nextPage": null,
"currentPageString": null,
"hasMore": true
}
}
Retrieve a Specific List
Retrieves a single list with the list ID equal to {id}. The list ID can be found using the retrieve all lists endpoint.
Example Response:
{
"contact_list_id": 2222,
"_brand_id": 123456789,
"name": "Join",
"description": “Join the VIP list”,
"created": "2024-01-01 15:36:40"
}
Edit a Specific List
Allows you to edit an existing list. You can target an existing list by passing the list ID in your PUT request. The list ID can be found using the retrieve all lists endpoint. At least one of the arguments below is required.
Arguments
| PARAMETER | DESCRIPTION |
|---|---|
| name | Name of the list. |
| description | Description of the list. |
Example Request Body:
{
"name": "Join",
"description": "Join the VIP list"
}
Example Response:
{
"contact_list_id": 2222,
"_brand_id": 123456789,
"name": "Join",
"description": “Join the VIP list”,
"created": "2024-01-01 15:36:40"
}
Create a List
Creates an empty list on this brand.
Arguments
| PARAMETER | DESCRIPTION |
|---|---|
| name (mandatory) | The name of the list you are creating. |
| description | Description of the list you are creating. |
Example Request Body:
{
"name": "Join",
"description": "Join the VIP list"
}
Example Response:
{
"contact_list_id": 2222,
"_brand_id": 123456789,
"name": "Join",
"description": “Join the VIP list”,
"created": "2024-01-01 15:36:40"
}
Delete a Specific List
Deletes an existing list with the list ID equal to {id}. The list ID can be found using the retrieve all lists endpoint. Using this action, the list is simply removed completely from the brand. Contacts that are currently in the list when the list is deleted will not be deleted. They will remain tied to your brand and any other list the contacts may be associated with.
Example Response:
[]
Retrieve Count of Contacts in Specific List
Returns the number of contacts in the list. This number is the total count of contacts. It will include any contacts that are unsubscribed, not subscribed, blocked, or subscribed.
Example Response:
1200
Retrieve Contacts from a Specific List
Retrieves all contacts associated with a specific list where list ID is equal to {id}. The list ID can be found using the retrieve all lists endpoint.
Example Response:
{
"data": [
{
"contact_id": 7778,
"_brand_id": 123456789,
"first_name": "Marty",
"last_name": "McFly",
"mobile_number": "+16155553338",
"mobile_number_carrier": null,
"email": "marty@slicktext.com",
"birthdate": "1968-06-12",
"address": "9303 Lyon Drive",
"city": "Hill Valley",
"state": "CA",
"zip": 95420,
"country": "US",
"source": "keyword",
"_source_id": "1111",
"sub_source": null,
"_sub_source_id": null,
"custom_fields": {
"member": 1,
"member_number": 12345,
"membership_date": "1985-10-26"
},
"timezone": "America/Los_Angeles",
"language": "en",
"opt_in_status": "subscribed",
"last_opt_in_status_change": "1955-11-12 06:38:00",
"created": "1955-11-12 06:38:00",
"last_updated": "2015-10-15 07:28:00"
}
],
"pagingData": {
"prevPage": null,
"currentPage": null,
"nextPage": null,
"currentPageString": null,
"hasMore": true
}
}
Add Contacts to Lists
Allows you to add one or more contacts to one or more lists. This is done by passing an array consisting of contact IDs with an array of list IDs each contact will be added to. The list ID can be found using the retrieve all lists endpoint. The contact ID can be found using the retrieve all contacts endpoint.
Arguments
| PARAMETER | DESCRIPTION |
|---|---|
| contact_id | Contact ID of contact you want to add to one or more lists. |
| lists[] | Array of list_id that represent the list(s) the contact will be added to. |
Example Request Body:
[
{
"contact_id": 1111,
"lists": [1000]
},
{
"contact_id": 2222,
"lists": [1000,1001]
}
]
Example Response:
{
"count": 3
}
Remove Contacts from Lists
Allows you to remove one or more contacts from one or more lists. This is done by passing an array consisting of contact IDs with an array of list IDs each contact will be removed from. The list ID can be found using the retrieve all lists endpoint. The contact ID can be found using the retrieve all contacts endpoint.
Arguments
| PARAMETER | DESCRIPTION |
|---|---|
| contact_id | Contact ID of contact you want to remove from one or more lists. |
| lists[] | Array of list_id that represent the list(s) the contact will be removed from. |
Example Request Body:
[
{
"contact_id": 1111,
"lists": [1000]
},
{
"contact_id": 2222,
"lists": [1000,1001]
}
]
Example Response:
{
"count": 3
}