The Contact resource now includes subresources for payload flexibility.

Contact Object and Subresources

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

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.

Subresource Properties Summary

Subresource Limit per Contact Character Limit Limit per Account
custom_fields 25 50 100
list_memberships 50 n/a 1000
phone_numbers 2 25 n/a
street_addresses 1 n/a n/a
taggings 50 255 500

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"
            ]
        },
        {
            "contact_id": "2d94c060-26cb-11e8-870b-fa163e6b01c2",
            "email_address": {
                "address": "srobillard+3@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": "last3",
            "last_name": "first3",
            "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"
            ]
       }
}

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

JAVA cURL PHP 
<?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.

PUT Request

You can include sub-resources when updating a contact resource directly in the request payload JSON. Any subresources that you do NOT include in a PUT are preserved, unlike the core contact properties which, when not included, are overwritten with a null value.

PUT call that adds or changes the custom_fields and phone_numbers subresources:

PUT https://api.cc.email/v3/contacts/{contact_id}

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

JAVA cURL PHP 
<?php

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

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

$request->setBody('{
  "email_address": {
      "address": "test123@example.com",
      "permission_to_send": "implicit",
      "created_at": "2013-11-26T15:45:35-05:00",
      "updated_at": "2013-11-26T15:45:35-05:00",
      "opt_in_source": "Account",
      "opt_in_date": "2013-11-26T15:45:35-05:00",
      "confirm_status": "off"
  },
    "update_source": "Contact"
},
  "street_addresses":[
    {
      "kind":"work",
      "street": "1313 Mockingbird Lane",
      "city": "Mockingbird Heights",
      "state": "Calivania",
      "postal_code": "99606-1313",
      "country": "United States"
  }
  ],
   "custom_fields": [{
      "custom_field_id": "{custom_field_id}",
      "value": "Tesla S 2017"
   }]
}');

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

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

curl -X PUT \
  https://api.cc.email/v3/contacts/{contact_id} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
  "email_address": {
      "address": "test123@example.com",
  },
    "update_source": "Contact"
},
  "street_addresses":[
    {
      "kind":"work",
      "street": "1313 Mockingbird Lane",
      "city": "Mockingbird Heights",
      "state": "Calivania",
      "postal_code": "99606-1313",
      "country": "United States"
  }
  ],
   "custom_fields": [{
      "custom_field_id": "{custom_field_id}",
      "value": "Tesla S 2017"
   }]
}'

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"email_address\": {\n\t    \"address\": \"test123@example.com\"\n\t},\n    \"update_source\": \"Contact\"\n},\n  \"street_addresses\":[\n    {\n      \"kind\":\"work\",\n      \"street\": \"1313 Mockingbird Lane\",\n      \"city\": \"Mockingbird Heights\",\n      \"state\": \"Calivania\",\n      \"postal_code\": \"99606-1313\",\n      \"country\": \"United States\"\n  }\n  ],\n   \"custom_fields\": [{\n      \"custom_field_id\": \"{custom_field_id}\",\n      \"value\": \"Tesla S 2017\"\n   }],\n   \n      \n      \"phone_numbers\": [\n    {\n      \"phone_number\": \"+1-555-555-5555\",\n      \"kind\": \"home\"\n    }\n  ]\n}");
Request request = new Request.Builder()
  .url("https://api.cc.email/v3/contacts/{contact_id}")
  .put(body)
  .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"
      }
    ],
    "custom_fields": [
      {
        "custom_field_id": "{custom_field_id}",
        "value": "Tesla S 2017"
      }]
}
Tags: contacts subresources custom_fields list_membership code_samples contacts_tags