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
<?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
<?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 |