Create a Single Contact

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 the EmailAddress object.
sms_channel: Specified using the ContactSmsChannel 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:writeAuthorization 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.

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.

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