Contact Resource

The contact object is composed of core properties and subresources. By default, V3 API contact response payloads only include the core properties.

Core Properties

For compliance reasons, when you first create a new contact, you must include the create_source property to document who added the contact to the account. Valid values are Contact or Account. This value is read-only going forward.

In addition to the create_source property, adding a new contact requires that you include at least one of the following properties:

• email_address : (string, Max Length: 80, required) The email address of the contact. The email address must be unique for each contact.

• first_name : (string, Max Length: 50) The first name of the contact.

• last_name : (string, Max Length: 50) The last name of the contact.

• sms_channel:

  • ContactSMSChannel ( object):
    • full_sms_address : (string, required) The contact’s SMS-compatible phone number including dial code. For example: 17815551212.
    • sms_consents : (array, required)
      • ContactSmsChannelConsents (object)
        • sms_consent_permission : (string, required) The current status of the channel. Enum: explicit. For example: explicit.
        • consent_type : (string, required) The type of consent provided. Enum: promotional_sms. For example: promotional_sms.
        • consent_medium_details : (string) Additional information for the consent. For example: details about the device.

Additional Core Properties

The following contact properties can also be specified:

• job_title: (string, maxLength: 50) Description: The contact’s job title. Example: "Musician"
• company_name: (string, maxLength: 50) Description: Name of the company the contact works for. Example: Acme Corp.
• birthday_month: (integer, maxLength: 2) Description: Accepts values from 1-12; must be used with birthday_day. Example: 11
• birthday_day: (integer, maxLength: 2) Description: Accepts values from 1-31; must be used with birthday_month. Example: 24

• anniversary: (string, maxLength: 10) Description: The anniversary date; Accepted formats are MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D, MM-DD-YYYY, M-D-YYYY. Example: 2006-11-15

• custom_fields: (array, maxItems: 25) Description: Array of up to 25 custom_field subresources.

• phone_numbers: (array, maxItems: 3) Description: Array of up to 3 phone_numbers subresources.

• street_addresses: (array, maxItems: 3) Description: Array of up to 3 street_addresses subresources.

Contact Subresources

Contact subresources can be included by using the include query parameter. Subresources give developers the option to streamline payload size when working with collections of contacts. This is good news for developers who need to consider payload size along with connection speed and bandwidth in designing and implementing their applications.

The following contact subresources are available:

Custom Fields

An array of custom fields (custom_field) to which the contact is assigned, up to a maximum of 25 key value pairs.

List Memberships

An array of contact lists (list_id) to which the contact is subscribed, up to a maximum of 50 lists.

Taggings

An array of tags (tag_id) to which a contact is assigned, up to a maximum of 50 tags.

Phone Numbers

An array of phone numbers (phone_numbers), up to a maximum of two phone numbers.

Street Addresses

An array of street addresses (street_addresses). A contact can have only one street address.

Notes

An array of up to 150 notes (notes) about a contact with most recent notes listed first.

Subresource Properties Summary

Example Results

{
    "contacts": [
        {
            "contact_id": "2d94c060-26cb-11e8-870a-fa163e6b01c2",
            "email_address": {
                "address": "srobillard+2@gmail.com",
                "permission_to_send": "implicit",
                "created_at": "2018-03-13T14:31:12Z",
                "updated_at": "2018-03-13T14:31:12Z",
                "opt_in_source": "Account",
                "opt_in_date": "2018-03-13T14:31:12Z",
                "confirm_status": "off"
            },
            "first_name": "last2",
            "last_name": "first2",
            "create_source": "Account",
            "created_at": "2018-03-13T14:31:12Z",
            "updated_at": "2018-03-13T14:31:12Z",
            "custom_fields": [],
            "phone_numbers": [],
            "street_addresses": [],
            "list_memberships": [
                "0385bea0-83ee-11e5-b6e3-00163e01f193",
                "257f81d0-26cb-11e8-8709-fa163e6b01c2",
                "48ce8380-fd9b-11e5-8cff-00163e01f193"
            ],
            "taggings": [
                "20a17970-26cb-11e8-ae38-fa163e56c9b1"
            ],
            "notes": [
               {
                 "note_id": "35043c66-afac-11e9-8077-fa163e56c9b0",
                 "created_at": "2021-07-26T13:49:37Z",
                 "content": "Contact resubscribed July 2021"
               }
            ],
            "sms_channel": {
               "sms_channel_id": "a93a61b6-4bd8-11ed-8e3b-fa163e595321",
               "sms_address": "7818800912",
               "dial_code": "1",
               "country_code": "US",
               "create_source": "Contact",
               "update_source": "Contact",
               "created_at": "2022-10-14T15:55:44Z",
               "updated_at": "2022-10-14T15:55:44Z",
               "sms_channel_consents": [
                   {
                      "sms_consent_permission": "pending_confirmation",
                      "consent_type": "Promotional_sms",
                      "advertised_frequency": 5,
                      "advertised_interval": "daily",
                      "confirmed": false,
                      "created_at": "2022-10-14T15:55:44Z",
                      "updated_at": "2022-10-14T15:55:44Z"
                   }
                 ]
              } 
              
         }
     ]   
}                    

Example Requests

GET Request

GET call for a single contact that includes the street_addresses subresource:

GET https://api.cc.email/v3/contacts/{contact_id}?include=street_address

Endpoint Requirements

User privileges: contacts:read

Authorization scopes: contact_data

<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contacts/{contact_id}');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'include' => 'street_addresses'
));

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

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

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

curl -X GET \
  'https://api.cc.email/v3/contacts/{contact_id}?include=street_addresses' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.cc.email/v3/contacts/{contact_id}?include=street_addresses")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {access_token}")
  .addHeader("Cache-Control", "no-cache")
  .build();

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

Response

{
    "contact_id": "{contact_id}",
    "email_address": {
        "address": "test123@example.com",
        "permission_to_send": "implicit",
        "created_at": "2013-11-26T15:46:13-05:00",
        "updated_at": "2016-10-28T14:34:35-04:00",
        "opt_in_source": "Account",
        "opt_in_date": "2018-11-26T15:46:13-05:00",
        "confirm_status": "off"
    },
    "first_name": "Tim",
    "last_name": "Jones",
    "update_source": "Contact",
    "create_source": "Account",
    "created_at": "2017-11-26T15:46:13-05:00",
    "updated_at": "2018-10-28T14:34:35-04:00",
    "street_addresses": [
        {
            "street_address_id": "{street_address_id}",
            "kind": "work",
            "street": "1313 Mockingbird Lane",
            "city": "Mockingbird Heights",
            "state": "California",
            "postal_code": "99606-1313",
            "country": "United States",
            "created_at": "2018-10-28T14:33:10-04:00",
            "updated_at": "2018-10-28T14:34:35-04:00"
        }
    ]
}

You can also get multiple subresources in a single request by using a comma separated list of subresources in the include query parameter.