Get details about a collection of contacts.

Use the GET /contacts endpoint to search for contacts in a user’s account that meet your search criteria. For example, your search criteria might include contact lists memberships and taggings or a specific date that the contact was created or updated.

By default, this method returns all contacts that are not deleted. Use the status query parameter with the value all to return all contacts including deleted contacts.

Search Criteria

Select from the following parameters to create your search criteria:

  • status - retrieve contacts with one or more of the following status: all, active, deleted, not_set, pending_confirmation, temp_hold, and unsubscribed.
  • exact email address
  • list membership - retrieve all contacts that are members of one or more lists.
  • tag ID - retrieve all contacts that are tagged with one or more specified tags (tag_id).
  • segment ID - retrieve all contacts to which a specified segment’s criteria applies. This query parameter can only be combined with the limit query parameter. When using the segment_id query parameter, the V3 API may return a 202 response code instead of a 200 response. The 202 response code indicates that your request has been accepted, but not fully completed. Retry sending your API request to return the completed results and a 200 response code.
  • updated date - retrieve all contacts with properties updated after (updated_after) date or before (updated_before) a specified date and time. To search for updated contacts within a date range, specify both updated_after and updated_before dates. Accepts ISO-8601 formatted dates.
  • created date - retrieve all contacts created after (created_after) date or (created-before) a specified date and time. To search for contacts created within a date range, specify both created_after and created_before dates. Accepts ISO-8601 formatted dates.
  • optout date - retrieve all contacts that opt out after or before (optout_after, optout_before) a specified date and time. Accepts ISO-8601 formatted dates.
  • SMS status - use the sms_status parameter to retrieve only those contacts that have a specified SMS status. Valid values include all, explicit, unsubscribed, pending_confirmation, and not_set. This parameter accepts one or more comma separated values.

Include Subresources

Subresources give developers the option to streamline payload size when working with collections of contacts.

Use the include parameter to get the subresources you want included in the results. Use a comma to separate multiple sub-resources. Valid values: custom_fields, list_memberships, taggings, notes, phone_numbers, street_addresses.

Learn more about contact resource and subresources.

Limit Results Per Page

Use the limit query parameter to limit the number of results returned per page. Use the link returned in the results to retrieve the next page of results.

Try it!

Request Example

The following request uses the status and updated_after parameters to return only those contacts that were updated after the specified date and that have a current status of unsubscribed. It also uses the limit parameter to return two results per page.

GET https://api.cc.email/v3/contacts

Endpoint Requirements

User privileges: contacts:read

Authorization scopes: contact_data

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cc.email/v3/contacts?status=unsubscribed&updated_after=2023-01-01T16%3A37%3A59.091Z&limit=2',
  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;

curl --location 'https://api.cc.email/v3/contacts?status=unsubscribed&updated_after=2023-01-01T16%3A37%3A59.091Z&limit=2' \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access token}'



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/contacts?status=unsubscribed&updated_after=2023-01-01T16:37:59.091Z&limit=2")
  .method("GET", body)
  .addHeader("Accept", "*/*")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "{access token}")
Response response = client.newCall(request).execute();

Response Example

{
    "contacts": [
        {
            "contact_id": "{contact_id}",
            "email_address": {
                "address": "myemail2@mzmail.com",
                "permission_to_send": "unsubscribed",
                "created_at": "2022-10-20T15:40:07Z",
                "updated_at": "2024-11-11T19:36:31Z",
                "opt_out_source": "Account",
                "opt_out_date": "2024-11-11T19:36:31Z",
                "confirm_status": "off"
            },
            "first_name": "bc_first_1000142",
            "last_name": "bc_last_1000142",
            "create_source": "Account",
            "created_at": "2022-10-20T15:40:08Z",
            "updated_at": "2024-11-11T21:33:47Z"
        },
        {
            "contact_id": "78ddef24-508d-11ed-a14c-a322292da29c",
            "email_address": {
                "address": "jmeter83057541000004@maildrop.nullmailer.com",
                "permission_to_send": "unsubscribed",
                "created_at": "2022-10-20T15:40:07Z",
                "updated_at": "2024-11-07T21:25:52Z",
                "opt_out_source": "Account",
                "opt_out_date": "2024-11-07T21:25:52Z",
                "confirm_status": "off"
            },
            "first_name": "bc_first_1000004",
            "last_name": "bc_last_1000004",
            "create_source": "Account",
            "created_at": "2022-10-20T15:40:08Z",
            "updated_at": "2024-11-07T21:25:54Z"
        }
    ],
    "_links": {
        "next": {
            "href": "/v3/contacts?cursor=cbkyMiZuZXh0PTImc3RhdHVzJTVCJTVEPXVuc3Vic2NyaWJlZCZ1cGRhdGVkX2FmdGVyPTIwMjMtMDEtMDFUMTYlM0EzNyUzQTU5JTJCMDAlM0EwMA=="
        }
    }
}

Try it! in the API Reference