To create a single new contact, make a POST call to the /contacts
endpoint. Contacts can choose to opt in to only receiving either email or SMS campaigns, or both.
The SMS product feature does not need to be enabled to include a contacts SMS details.
When creating a new contact, you must include the create_source
property and one or both of the following:
-
email_address
: The unique email address specified using theEmailAddress
object. -
sms_channel
: Specified using theContactSmsChannel
object.full_sms_address
:(string, required). The unique SMS-capable phone number for the Contact, including the dial code.sms_channel_consents
: [(array[ContactSmsChannelConsents],required). The consents for the SMS Channel.sms_consent_permission
:(string, required). The current status of the SMS channel.consent_type
: (string, required). The type of consent provided.consent_medium_details
: (string). Additional information about the consent, such as the type of device used.
To learn more about optional contact properties and subresources you can include, see Contact Subresources.
Request Examples
POST https://api.cc.email/v3/contacts
Endpoint Requirements
User privileges: contacts:write
Authorization scopes: contact_data
Create a new Contact - Email and SMS
The request example that follows creates a new contact and adds the contact’s email and SMS phone information.
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.cc.email/v3/contacts',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"email_address": {
"address": "dlang22@example.com",
"permission_to_send": "implicit"
},
"first_name": "Debora",
"last_name": "Lang",
"job_title": "Musician",
"company_name": "Acme Corp.",
"create_source": "Account",
"birthday_month": 11,
"birthday_day": 24,
"anniversary": "2006-11-15",
"phone_numbers": [
{
"phone_number": "+1-555-555-5555",
"kind": "home"
}
],
"street_addresses": [
{
"kind": "home",
"street": "123 Kashmir Valley Road",
"city": "Chicago",
"state": "Illinois",
"postal_code": "60609",
"country": "United States"
}
],
"sms_channel": {
"full_sms_address": "17815551213",
"sms_channel_consents": [
{
"sms_consent_permission": "explicit",
"consent_type": "promotional_sms",
"consent_medium_details": "IPhone 13 device used to provide consent."
}
]
}
}',
CURLOPT_HTTPHEADER => array(
'Accept: */*',
'Content-Type: application/json',
'Authorization: Bearer {access token}'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
curl --location 'https://api.cc.email/v3/contacts' \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: 'Bearer {access token}'\
--data-raw '{
"email_address": {
"address": "dlang22@example.com",
"permission_to_send": "implicit"
},
"first_name": "Debora",
"last_name": "Lang",
"job_title": "Musician",
"company_name": "Acme Corp.",
"create_source": "Account",
"birthday_month": 11,
"birthday_day": 24,
"anniversary": "2006-11-15",
"phone_numbers": [
{
"phone_number": "+1-555-555-5555",
"kind": "home"
}
],
"street_addresses": [
{
"kind": "home",
"street": "123 Kashmir Valley Road",
"city": "Chicago",
"state": "Illinois",
"postal_code": "60609",
"country": "United States"
}
],
"sms_channel": {
"full_sms_address": "17815551213",
"sms_channel_consents": [
{
"sms_consent_permission": "explicit",
"consent_type": "promotional_sms",
"consent_medium_details": "IPhone 13 device used to provide consent."
}
]
}
}'
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"email_address\": {\n \"address\": \"dlang22@example.com\",\n \"permission_to_send\": \"implicit\"\n },\n \"first_name\": \"Debora\",\n \"last_name\": \"Lang\",\n \"job_title\": \"Musician\",\n \"company_name\": \"Acme Corp.\",\n \"create_source\": \"Account\",\n \"birthday_month\": 11,\n \"birthday_day\": 24,\n \"anniversary\": \"2006-11-15\",\n \"phone_numbers\": [\n {\n \"phone_number\": \"+1-555-555-5555\",\n \"kind\": \"home\"\n }\n ],\n \"street_addresses\": [\n {\n \"kind\": \"home\",\n \"street\": \"123 Kashmir Valley Road\",\n \"city\": \"Chicago\",\n \"state\": \"Illinois\",\n \"postal_code\": \"60609\",\n \"country\": \"United States\"\n }\n ],\n \"sms_channel\": {\n \"full_sms_address\": \"17815551213\",\n \"sms_channel_consents\": [\n {\n \"sms_consent_permission\": \"explicit\",\n \"consent_type\": \"promotional_sms\",\n \"consent_medium_details\": \"IPhone 13 device used to provide consent.\"\n }\n ]\n }\n}");
Request request = new Request.Builder()
.url("https://api.cc.email/v3/contacts")
.method("POST", body)
.addHeader("Accept", "*/*")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {access token}")
.build();
Response response = client.newCall(request).execute();
Response Example
{
"contact_id": "d9dc542c-c935-11ef-b404-d347037f41dd",
"first_name": "Debora",
"last_name": "Lang",
"email_address": {
"address": "dlang22@example.com",
"permission_to_send": "implicit",
"created_at": "2025-01-02T18:17:33Z",
"updated_at": "2025-01-02T18:17:33Z",
"channel_id": "d5e95e74-c935-11ef-90b4-9d8fcb6d78b6",
"opt_in_source": "Account",
"opt_in_date": "2025-01-02T18:17:33+00:00",
"confirm_status": "off"
},
"job_title": "Musician",
"company_name": "Acme Corp.",
"birthday_month": 11,
"birthday_day": 24,
"anniversary": "2006-11-15",
"create_source": "Account",
"source_name": "Site Owner",
"source_details": "Single Add",
"created_at": "2025-01-02T18:17:33Z",
"updated_at": "2025-01-02T18:17:33Z",
"phone_numbers": [
{
"phone_number_id": "d5e52a66-c935-11ef-8e66-63386406c598",
"phone_number": "+1-555-555-5555",
"kind": "home",
"created_at": "2025-01-02T18:17:33Z",
"updated_at": "2025-01-02T18:17:33Z"
}
],
"street_addresses": [
{
"street_address_id": "d5e840de-c935-11ef-8dee-f568a97d9902",
"kind": "home",
"street": "123 Kashmir Valley Road",
"city": "Chicago",
"state": "Illinois",
"postal_code": "60609",
"country": "United States",
"created_at": "2025-01-02T18:17:33Z",
"updated_at": "2025-01-02T18:17:33Z"
}
],
"sms_channel": {
"sms_channel_id": "d5e64892-c935-11ef-ae61-ade70b8a5bc5",
"sms_address": "7815551213",
"dial_code": "1",
"country_code": "US",
"create_source": "Account",
"update_source": "Account",
"created_at": "2025-01-02T18:17:33Z",
"updated_at": "2025-01-02T18:17:33Z",
"sms_channel_consents": [
{
"sms_consent_permission": "explicit",
"consent_type": "Promotional_sms",
"opt_in_date": "2025-01-02T18:17:32Z",
"confirmed": false,
"created_at": "2025-01-02T18:17:33Z",
"updated_at": "2025-01-02T18:17:33Z"
}
]
}
}
Create a new Contact - SMS Only
The request example that follows creates a new contact and adds the contact’s SMS phone information.
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.cc.email/v3/contacts',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"create_source": "Account",
"first_name": "Holly",
"last_name": "Lang",
"sms_channel": {
"full_sms_address": "17815551219",
"sms_channel_consents": [
{
"sms_consent_permission": "explicit",
"consent_type": "promotional_sms",
"consent_medium_details": "IPhone 13 device used to provide consent."
}
]
}
}',
CURLOPT_HTTPHEADER => array(
'Accept: */*',
'Content-Type: application/json',
'Authorization: Bearer {token}'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
curl --location 'https://api.cc.email/v3/contacts' \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{
"create_source": "Account",
"first_name": "Holly",
"last_name": "Lang",
"sms_channel": {
"full_sms_address": "17815551219",
"sms_channel_consents": [
{
"sms_consent_permission": "explicit",
"consent_type": "promotional_sms",
"consent_medium_details": "IPhone 13 device used to provide consent."
}
]
}
}'
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"create_source\": \"Account\",\n \"first_name\": \"Holly\",\n \"last_name\": \"Lang\",\n \"sms_channel\": {\n \"full_sms_address\": \"17815551219\",\n \"sms_channel_consents\": [\n {\n \"sms_consent_permission\": \"explicit\",\n \"consent_type\": \"promotional_sms\",\n \"consent_medium_details\": \"IPhone 13 device used to provide consent.\"\n }\n ]\n } \n}");
Request request = new Request.Builder()
.url("https://api.cc.email/v3/contacts")
.method("POST", body)
.addHeader("Accept", "*/*")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {token}")
.build();
Response response = client.newCall(request).execute();
Response Example for SMS-Only Contact
The request example that follows creates a new contact and adds the contact’s email and SMS phone information.
{
"contact_id": "10be1f88-cdea-11ef-8bba-4b3d614895c4",
"first_name": "Holly",
"last_name": "Lang",
"create_source": "Account",
"source_name": "Site Owner",
"source_details": "Single Add",
"created_at": "2025-01-08T18:01:29Z",
"updated_at": "2025-01-08T18:01:29Z",
"sms_channel": {
"sms_channel_id": "95bf02cc-cdea-11ef-9944-f3a19969d036",
"sms_address": "7815551219",
"dial_code": "1",
"country_code": "US",
"create_source": "Account",
"update_source": "Account",
"created_at": "2025-01-08T18:01:29Z",
"updated_at": "2025-01-08T18:01:29Z",
"sms_channel_consents": [
{
"sms_consent_permission": "explicit",
"consent_type": "Promotional_sms",
"opt_in_date": "2025-01-08T18:01:29Z",
"confirmed": false,
"created_at": "2025-01-08T18:01:29Z",
"updated_at": "2025-01-08T18:01:29Z"
}
]
}
}