How to add large numbers of contacts to lists using bulk activity endpoints

Use the /activities/add_list_memberships endpoint to quickly add large numbers of contacts to one or more existing lists. This endpoint allows you to specify the contacts to add to lists in one of three mutually exclusive ways:

  • by contact_id - you can specify up to 500 individual contacts by contact_id
  • by list_id - all contacts that are members of up to 50 lists
  • all_active_contacts - all active contacts on the user’s account

You can add contacts to as many as 50 existing lists in the user’s account in one POST call to this endpoint.

JSON Request Payload

The JSON request payload consists of two main components:

  • Source - identifies the contacts you wanted added to lists
  • list_ids - identifies the lists to which the contacts will be added

Source - Identify Contacts to Add

The source object in the request payload identifies which contacts will be added to lists. It can contain one of four properties that identify the contacts that will be added to lists:

  • contact_ids - an array of up to 500 individual contact_id values
  • list_ids - an array of up to 50 individual list_id values. All contacts that are members of these “source” lists will be added to the “destination” lists.
  • all_active_contacts - a boolean that, when set to true, adds all active contacts in the user’s account to the “destination” lists.

Destination Lists

The list_ids array (outside of the source object) identifies the lists to which contacts will be added. It can contain up to 50 list_id values.

Example Request Body

This example will add all contacts in the contact_ids array to the 3 lists in the list_ids array.

{
  "source": {
    "contact_ids": [
      "{contact_id_1}",
      "{contact_id_2}",
      "{contact_id_2}"
    ]
  },
  "list_ids": [
    "{list_id_1}",
    "{list_id_2}",
    "{list_id_3}"
  ]
}

Example Request

POST https://api.cc.email/v3/activities/add_list_memberships

<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/activities/add_list_memberships');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Content-Type' => 'application/json',
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access_token}',
  'Cache-Control' => 'no-cache'
));

$request->setBody('{
  "source": {
    "contact_ids": [
      "{contact_id_1}",
      "{contact_id_2}",
      "{contact_id_2}"
    ]
  },
  "list_ids": [
     "{list_id_1}",
     "{list_id_2}",
     "{list_id_3}"
  ]
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
curl -X POST \
  https://api.cc.email/v3/activities/add_list_memberships \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Cache-Control: no-cache' \
  -d '{
  "source": {
    "contact_ids": [
      "{contact_id_1}",
      "{contact_id_2}",
      "{contact_id_2}"
    ]
  },
  "list_ids": [
     "{list_id_1}",
     "{list_id_2}",
     "{list_id_3}"
  ]
}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"source\": {\n    \"contact_ids\": [\n     \t\"{contact_id_1}\",\n  \t\t\"{contact_id_2}\",\n  \t\t\"{contact_id_2}\"\n    ]\n  },\n  \"list_ids\": [\n\t   \"{list_id_1}\",\n\t   \"{list_id_2}\",\n\t   \"{list_id_3}\"\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.cc.email/v3/activities/add_list_memberships")
  .post(body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Accept", "application/json")
  .addHeader("Authorization", "Bearer {access_token}")
  .addHeader("Cache-Control", "no-cache")
  .build();

Response response = client.newCall(request).execute();

Example Response

{
    "activity_id": "{activity_id}",
    "state": "initialized",
    "created_at": "2017-11-07T13:00:54-05:00",
    "updated_at": "2017-11-07T13:00:54-05:00",
    "percent_done": 1,
    "activity_errors": [],
    "status": {},
    "_links": {
        "self": {
            "href": "/v3/activities/{activity_id}"
        }
    }
}