How to Add Contacts to Lists

Use the /activities/add_list_memberships endpoint to quickly add large numbers of contacts to one or more existing lists. You can add contacts to as many as 50 existing lists in the user’s account in one POST call.

JSON Request Payload

The JSON request payload consists of the following components:

Source - Identify Contacts to Add

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

• 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 (billable) contacts in the user’s account to the “destination” lists.
• new_subscriber - set to true to add all contacts that subscribed within the last 30 days to the specified target lists. Use with the exclude object to exclude certain contacts (by contact_id) from being added to the specified target lists.
• engagement_level - adds all contacts that meet the selected engagement_level (unqualified, low, medium, high) to your target lists. This property is mutually exclusive with all other source properties.
• segment_id - system generated ID (integer) used to get all contacts that meet the specified segment’s criteria.
• tag_ids - an array of up to 50 tag_ids used to identify which tagged contacts to add to the destination lists.
• engagement_level - adds all contacts that meet the selected engagement level (unqualified, low, medium, high) to your target lists.

Exclude

If using all_active_contacts or list_ids as the source, you can use the exclude object to identify contacts, by contact_id, that you do not want to add to the target contact lists.

Exclude

If using all_active_contacts or list_ids as the source, you can use the exclude object to identify contacts, by contact_id, that you do not want to add to the target contact 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 three 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

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

<?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}"
        }
    }
}

Try it!

[]: