The Contact resource now includes subresources for payload flexibility.

Contact Object 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. Here are the contact subresources currently available:

  • Custom Fields
  • List Memberships
  • Phone Numbers
  • Street Addresses

This is good news for developers who need to consider payload size along with connection speed and bandwidth in designing and implementing their applications.

Example 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.

Example PUT Request

You can include subresources 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"
      }]
}

List Memberships

The list_memberships subresource tells you the lists to which the contact is subscribed; it is expressed as an array of list_ids. A contact can be a member of up to a maximum of 50 lists.

Contact 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
Tags: contacts subresources custom_fields list_membership code_samples