Quickly remove contacts from as many as 50 specified contact lists by making a single Post
call to the /activities/remove_list_memberships
endpoint. In the JSON request, you select the contact lists you want to remove contacts from and the source to use to identify which contacts to remove.
JSON Request Payload
Source
To identify which contacts to remove from target contact lists, choose from one of the following mutually exclusive source
options:
contact_ids
- Specify an array of up to 500 contacts (contact_id
).list_ids
- Specify an array of up to 100 contact lists (list_id
). Use with theexclude
object to exclude certain contacts (bycontact_id
) from being removed from the specified target lists.all_active_contacts
- Set totrue
to remove all active (billable) contacts from the specified target lists.tag_ids
- Specify an array of up to 50tag_id
s to remove all contacts with those tags from the specified target lists.engagement_level
- removes all contacts that meet the selected engagement level (unqualified
,low
,medium
,high
) from your target lists.
Exclude
If using all_active_contacts
or list_ids
as the source, you can use the exclude
object to identify contacts (contact_id
) that you do not want to remove from the target contact lists.
Target Contact Lists
Use the list_ids
object to identify up to 50 target contact lists (list_id
) from which you want contacts removed.
Example Request
POST https://api.cc.email/v3/activities/remove_list_memberships
Endpoint Requirements
User privileges: contacts:write
Authorization scopes: contact_data
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.cc.email/v3/activities/remove_list_memberships',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"source": {
"tag_ids": [
"31a17970-26cb-11e8-ae38-fa163e56c9b0"
]
},
"list_ids": [
"131a3f10-01ab-11e6-8106-00163e6dbd8c"
]
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Authorization' => 'Bearer {access_token}'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
curl --location 'https://api.cc.email/v3/activities/remove_list_memberships' \
--header 'Content-Type: application/json' \
--header 'Authorization' => 'Bearer {access_token}' \
--data '{
"source": {
"tag_ids": [
"31a17970-26cb-11e8-ae38-fa163e56c9b0"
]
},
"list_ids": [
"131a3f10-01ab-11e6-8106-00163e6dbd8c"
]
}'
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"source\": {\n \"tag_ids\": [\n \"31a17970-26cb-11e8-ae38-fa163e56c9b0\"\n ]\n },\n \"list_ids\": [\n \"131a3f10-01ab-11e6-8106-00163e6dbd8c\"\n ]\n}");
Request request = new Request.Builder()
.url("https://api.cc.email/v3/activities/remove_list_memberships")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {access_token}")
.build();
Response response = client.newCall(request).execute();
Example Response
The response returns activity details and the URL you use to check the activity status.
{
"activity_id": "{activity_id}",
"state": "initialized",
"created_at": "2024-01-23T13:48:44.108Z",
"updated_at": "2024-01-23T13:48:44.108Z",
"percent_done": 1,
"activity_errors": [
"Message describing the error condition."
],
"status": {
"list_count": 1
},
"_links": {
"self": {
"href": "/v3/activities/{activity_id}"
}
}
}
Checking the Activity Status for Job Complete
Check the activity status and when Constant Contact has completed processing an activity by making a GET
call to /activities/{activity_id}
using the activity_id
located in the _links
section of the response.
GET https://api.cc.email/v3/activities/{activity_id}
Endpoint Requirements
User privileges: contacts:write
Authorization scopes: contact_data