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
.
- ContactSmsChannelConsents (object)
- ContactSMSChannel ( object):
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 withbirthday_day
. Example:11
birthday_day
: (integer, maxLength: 2) Description: Accepts values from 1-31; must be used withbirthday_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 25custom_field
subresources. -
phone_numbers
: (array, maxItems: 3) Description: Array of up to 3phone_numbers
subresources. street_addresses
: (array, maxItems: 3) Description: Array of up to 3street_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
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 |
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.