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 thelimit
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 theinclude_count
parameter totrue
(default isfalse
). -
include_membership_count
: To include the total number for active contacts (mailable contacts) per list, set the parameter toactive
, or set it toall
to return all contacts that are members on a list. -
status
: To get lists based on a list’s status, set thestatus
query parameter to eitheractive
,deleted
, orall
. Accepts one or more comma separated status values. -
name
: To return a list by name, use thename
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, setfavorite
totrue
. -
membership_count
: If theinclude_membership_count
query parameter is set, the results include the total contact count for each list. If the value is set toall
, the count includes all contacts that are list members. If the value is set toactive
, 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.
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.