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

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

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.

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.

JAVA cURL PHP 
<?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

JAVA cURL PHP 
<?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"
}

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

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.

Tags: contacts code_samples