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 contact collection 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

POST https://api.cc.email/v3/contacts

Create a new contact by making a POST call to the contact collection 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 our system receives a POST request to add a new contact, we check to see if the email address already exists in the user’s account. We return a 409 Conflict response if it does.

Avoiding 409 Responses

TIP: To avoid a 409 Conflict response when creating a new contact, have your integration check to see if the email address for the new contact exists in the user's account before making a POST request to add a new contact.

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

This call returns a 200 OK with an empty response if the email address does not exist in the user’s account. If the email already exists, the call returns a 200 OK and the contact object. You’re integration needs to provide the proper messaging that the email address is already subscribed.

Example POST 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!

Adding 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.

Populating a New 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 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.