Removes a large numbers of contacts from contact lists using a bulk activity endpoint.

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 the exclude object to exclude certain contacts (by contact_id) from being removed from the specified target lists.
  • all_active_contacts - Set to true to remove all active (billable) contacts from the specified target lists.
  • tag_ids - Specify an array of up to 50 tag_ids 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

Try it!