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
By default, the first set of 50 Lists will be returned, but you can modify this number with limit and offset values in the query string. The max limit for a single request is 10,000. You can also retrieve your data with pagination. You do this by passing the page and pageSize query string parameters. Page determines which page number to be returned and pageSize determines the number of Lists returned in that page.
When retrieving multiple lists, you may also want to include additional criteria in the query string to filter the results by. Any field that is included in the resources is available for use as a filter. These are exact matches; they are case-sensitive and do not allow wildcards.
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}.
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. 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}. 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
By default, the first set of 50 Contacts will be returned, but you can modify this number with limit and offset values in the query string. The max limit for a single request is 10,000. You can also retrieve your data with pagination. You do this by passing the page and pageSize query string parameters. Page determines which page number to be returned and pageSize will determine the number of Contacts returned in that page.
When retrieving multiple lists, you may also want to include additional criteria in the query string to filter the results by. Any field that is included in the resources is available for use as a filter. These are exact matches; they are case-sensitive and do not allow wildcards.
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.
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.
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
}