Best practices to follow when adding new contacts in the V3 API.

There are two ways to add contacts to an account using the V3 API:

  • Create a single new contact using a POST call to the contacts endpoint.
  • Create multiple contacts with a single API call using 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

TIP: 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.

Example GET Contacts Using Email Address Request

GET https://api.cc.email/v3/contacts?email=new_contact_email

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.

<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/contacts');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'email' => 'new_contact_email'
));

$request->setHeaders(array(
  'Postman-Token' => '66452581-b040-4eb1-b41a-fe38ba7f3ad6',
  'cache-control' => 'no-cache',
  'Authorization' => 'Bearer ons0epj6HlSollE3rmxdGEA7CNVF',
  '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' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer ons0epj6HlSollE3rmxdGEA7CNVF' \
  -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")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer ons0epj6HlSollE3rmxdGEA7CNVF")
  .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

<?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": "danipper@example.com",
    "permission_to_send": "implicit"
  },
  "first_name": "David",
  "last_name": "Nipper",
  "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": "danipper@example.com",
    "permission_to_send": "implicit"
  },
  "first_name": "David",
  "last_name": "Nipper",
  "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\": \"danipper@example.com\",\r\n    \"permission_to_send\": \"implicit\"\r\n  },\r\n  \"first_name\": \"David\",\r\n  \"last_name\": \"Nipper\",\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": "danipper@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": "David",
  "last_name": "Nipper",
  "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"
}

Try it!

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

  1. Create the new list.
  2. Collect the contacts to import from the local source.
  3. Format the data to match the requirements of the activity import endpoint you will use, either a csv file or a json payload.
  4. Import the contacts by making a POST call to the appropriate Constant Contact bulk activity import endpoint.
  5. Check the activity status to watch for when the job completes. Learn how here.
  6. 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

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.