There are three ways to add contacts to an account using the V3 API:
- Create a single new contact by making a POST call to the
/contacts
endpoint. - Create a single new contact or update an existing contact by making a POST call to the
/contacts/sign_up_form
endpoint. For more information on using this method, see Create or Update a Contact. - Create multiple contacts with a single API call by making a POST call to a bulk activity endpoint.
New contacts may be sent an Autoresponder Welcome Email or a Confirm Opt-in email, learn more here.
Add a Single Contact
Create a new contact by making a POST call to the /contacts
endpoint. The request payload must include at least one of the following contact properties:
first_name
last_name
email_address
(must be unique)
Use this method for adding small numbers of contacts individually. When you sent a POST request to add a new contact, Constant Contact checks to see if the contact’s email already exists in the user’s account. If the email already exists, Constant Contact returns a 409 conflict response code.
Avoiding 409 Responses
To avoid getting a 409 Conflict response when you create a new contact, check to see if the email address for the new contact exists in the user's account before you make a POST request to add a new contact.
You can also use the POST /contacts/sign_up_form
endpoint instead of the POST /contacts
endpoint to avoid 409 conflicts due to an existing contact. The /contacts/sign_up_form
endpoint creates a new contact if the email address you provide is new and updates an existing contact if the email address already exists in the user's account. For more information, see Create or Update a Contact Using a Single Method.
Example GET Contacts Using Email Address Request
GET https://api.cc.email/v3/contacts?email=new_contact_email&status=all
Endpoint Requirements
User privileges: contacts:read
Authorization scopes: contact_data
If the email address does not exist in the user’s account, the call returns a 200 OK and an empty array. If the email already exists, the call returns a 200 OK and the corresponding contact object. If the email address already exists in the user’s account, your integration needs to provide the proper messaging that the email address is already subscribed.
Make sure that you use the status
query parameter with the value all
when you check if the email address exists in the user’s account. This allows you to confirm if the email address already exists in the account even when the contact is deleted.
<?php
$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contacts');
$request->setMethod(HTTP_METH_GET);
$request->setQueryData(array(
'email' => 'new_contact_email',
'status' => 'all'
));
$request->setHeaders(array(
'Postman-Token' => '66452581-b040-4eb1-b41a-fe38ba7f3ad6',
'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?email=new_contact_email&status=all' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-H 'Postman-Token: 98980ee6-b99f-41a9-9a7a-3b5651d2ea7f' \
-H 'cache-control: no-cache'
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://api.cc.email/v3/contacts?email=new_contact_email&status=all")
.get()
.addHeader("Accept", "application/json")
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {access_token}")
.addHeader("cache-control", "no-cache")
.addHeader("Postman-Token", "851265ff-454f-4d2f-a619-db0c8f0bd627")
.build();
Response response = client.newCall(request).execute();
Response
{
"contacts": []
}
Example POST Create a Contact Request
POST https://api.cc.email/v3/contacts
Endpoint Requirements
User privileges: contacts:write
Authorization scopes: contact_data
<?php
$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contacts');
$request->setMethod(HTTP_METH_POST);
$request->setHeaders(array(
'cache-control' => 'no-cache',
'authorization' => 'Bearer {access_token}',
'content-type' => 'application/json',
'accept' => 'application/json'
));
$request->setBody('{
"email_address": {
"address": "dlang@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",
"steet_addresses":{
"kind":"home",
"street": "123 Kashmir Valley Road",
"city": "Chicago",
"state": "Illinois",
"country": "United States",
}
}');
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
curl -X POST \
https://api.cc.email/v3/contacts \
-H 'accept: application/json' \
-H 'authorization: Bearer {access_token}' \
-H 'cache-control: no-cache' \
-H 'content-type: application/json' \
-d '{
"email_address": {
"address": "dlang@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",
"steet_addresses":{
"kind":"home",
"street": "123 Kashmir Valley Road",
"city": "Chicago",
"state": "Illinois",
"country": "United States",
}
}'
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "{\r\n \"email_address\": {\r\n \"address\": \"dlang@example.com\",\r\n \"permission_to_send\": \"implicit\"\r\n },\r\n \"first_name\": \"Debora\",\r\n \"last_name\": \"Lang\",\r\n \"job_title\": \"Musician\",\r\n \"company_name\": \"Acme Corp.\",\r\n \"create_source\": \"Account\",\r\n \"birthday_month\": 11,\r\n \"birthday_day\": 24,\r\n \"anniversary\": \"2006-11-15\",\r\n \"steet_addresses\":{\r\n \"kind\":\"home\",\r\n \"street\": \"123 Kashmir Valley Road\",\r\n \"city\": \"Chicago\",\r\n \"state\": \"Illinois\",\r\n \"country\": \"United States\",\r\n }\r\n}");
Request request = new Request.Builder()
.url("https://api.cc.email/v3/contacts")
.post(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": "dlang@example.com",
"permission_to_send": "implicit",
"created_at": "2018-02-23T13:38:28-05:00",
"updated_at": "2018-02-23T13:38:28-05:00",
"opt_in_source": "Account",
"opt_in_date": "2018-02-23T13:38:28-05:00",
"confirm_status": "off"
},
"first_name": "Debora",
"last_name": "Lang",
"job_title": "Musician",
"company_name": "Acme Corp.",
"birthday_month": 11,
"birthday_day": 24,
"anniversary": "2006-11-15",
"create_source": "Account",
"created_at": "2018-02-23T13:38:28-05:00",
"updated_at": "2018-02-23T13:38:28-05:00"
}
Add Many Contacts
You can import thousands of contacts in a single API call using either of the two Contacts Import endpoints. One endpoint supports a JSON payload, the other imports from a CSV file, learn more.
Guidelines for Importing Contacts
The process described here imports new contacts from a local source into Constant Contact.
Populate a New Contacts List
- Create the new list.
- Collect the contacts to import from the local source.
- Format the data to match the requirements of the activity import endpoint you will use, either a csv file or a json payload.
- Import the contacts by making a POST call to the appropriate Constant Contact bulk activity import endpoint.
- Check the activity status to watch for when the job completes. Learn how here.
- When the import activity completes, all contacts are imported into Constant Contact and any errors are noted in the activity status.
Confirm the list membership by making the following call to the GET contact collection endpoint to get all contacts on the newly created list:
GET https://api.cc.email/v3/contacts?lists=list_id
Endpoint Requirements
User privileges: contacts:read
Authorization scopes: contact_data
It’s important to keep the local source in sync with the Constant Contact data. Check out How to Sync Contacts and Lists for more information.