Get all contact lists in your account.

To get details about contact lists in your account, make a GET call to the /contact_lists endpoint.

To get additional details about your contact lists or to limit the number of lists to return per page, choose from the query parameters that follow.

  • limit: To limit the number of lists returned per page, set the limit value to a number in the range of 1 to 1000, inclusively. The default value is 1000.

  • include_count: To include the total number of contact lists for the account in the results, set the include_count parameter to true (default is false).

  • include_membership_count: To include the total number for active contacts (mailable contacts) per list, set the parameter to active, or set it to all to return all contacts that are members on a list.

  • status: To get lists based on a list’s status, set the status query parameter to either active, deleted, or all. Accepts one or more comma separated status values.

  • name: To return a list by name, use the name query parameter and enter the list’s full name.

Example Request

This example request uses the include_count, status and include_membership_count query parameters.

GET https://api.cc.email/v3/contact_lists?include_count=true&include_membership_count=all

Endpoint Requirements

User privileges: contacts:read

Authorization scopes: contact_data

OkHttpClient client=new OkHttpClient().newBuilder()
        .build();
        MediaType mediaType=MediaType.parse("application/json");
        RequestBody body=RequestBody.create(mediaType,"");
        Request request=new Request.Builder()
        .url("https://api.cc.email/v3/contact_lists?include_count=true&status=active&include_membership_count=all")
        .method("GET",body)
        .addHeader("Accept","*/*")
        .addHeader("Content-Type","application/json")
        .addHeader("Authorization","Bearer {access_token}")
        .build();
        Response response=client.newCall(request).execute();
curl --location --request GET 'https://api.cc.email/v3/contact_lists?include_count=true&status=active&include_membership_count=all' \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}'
<?php
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cc.email/v3/contact_lists?include_count=true&status=active&include_membership_count=all',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Accept: */*',
    'Content-Type: application/json',
    'Authorization: Bearer {access_token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Example Response

{
    "lists_count": 5,
    "lists": [
        {
            "list_id": "50429486-338f-11ed-a355-fa163ef30863",
            "sequence_id": 1484646966,
            "name": "ImportList",
            "dynamic_filtered_list": false,
            "created_at": "2022-09-13T18:10:13Z",
            "updated_at": "2022-09-13T18:10:13Z",
            "favorite": false,
            "membership_count": 28,
        },
        {
            "list_id": "58d08406-38f7-11ed-a2bd-fa163e595591",
            "sequence_id": 1620038745,
            "name": "Unsubscribed",
            "dynamic_filtered_list": false,
            "created_at": "2022-09-20T15:17:31Z",
            "updated_at": "2022-09-20T15:17:31Z",
            "favorite": false,
            "membership_count": 0,
        },
        {
            "list_id": "7da85760-3e71-11ed-9bf0-fa163e123456",
            "name": "NewContacts",
            "description": "List of repeat customers",
            "created_at": "2023-02-08T19:04:52Z",
            "updated_at": "2023-02-08T19:04:52Z",
            "favorite": false,
            "membership_count": 0,
        },
        {
            "list_id": "8da85760-3e71-11ed-9bf0-fa163e123456",
            "name": "GoldList",
            "created_at": "2022-09-27T14:34:54Z",
            "updated_at": "2022-09-27T14:34:54Z",
            "favorite": false,
            "membership_count": 23,
        },
        {
            "list_id": "9ca85760-3e71-11ed-9bf0-fa163e123456",
            "name": "membersOnly",
            "description": "Members",
            "created_at": "2022-10-07T15:35:17Z",
            "updated_at": "2023-02-02T21:51:40Z",
            "favorite": true,
            "membership_count": 11,
        }    
    ]
}     

Response details include the following:

  • list_id: The lists unique ID.

  • name: The name of the contact list.

  • created_at: The system generated date and time that the resource was created, in ISO-8601 format.

  • updated_at: The system generated date and time that the resource was last updated, in ISO-8601 format.

  • favorite: Identifies if the contact list was favorited. To favorite a list, make the PUT call to the /contact_lists/{list_id} endpoint and in the request body, set favorite to true.

  • membership_count: If the include_membership_count query parameter is set, the results include the total contact count for each list. If the value is set to all, the count includes all contacts that are list members. If the value is set to active, the count includes only active (mailable) contacts that are list members.

  • lists_count: The total number of contact lists in the results.

  • include_membership_count: The total number for active contacts (mailable contacts) per list.

Try it!

What’s Next

If you want to get contact details for a particular list, make a GET call to the /contacts?lists={list_id1} endpoint. Use the lists query parameter to specify which lists to use. The response includes contact details, such as contact_id,first_name, last_name, job_title, and more. Try it!

Constant Contact does not sell or rent email addresses. Users are not permitted to upload or use purchased, traded, shared, or borrowed lists to their Constant Contact account.

Review our permission policy for more information.