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.
Notes
An array of up to 150 notes (notes
) about a contact with most recent notes listed first.
SMS Channel and Consent Details
An object (sms_channel
) containing SMS channel information, including consent details (sms_channel_consents
array).
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 |
notes | 150 | 2000 | n/a |
sms_channel | n/a | n/a | n/a |
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",
"source_ip": "8.8.8.8",
"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.
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
<?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"
}]
}