How to import and update large numbers of contacts using bulk activity endpoints

There are two ways to import contacts from another source into a Constant Contact account:

  • Use the /activities/contacts_file_import endpoint to import contacts using a CSV file for the payload
  • Use the /activities/contacts_json_import endpoint to import contacts using a JSON formattted payload
You can use these endpoints to import new contacts and update existing contacts when syncing local data w/Constant Contact.

For existing contacts, only the properties included in the import will be updated. All other data will remain unchanged for existing contacts.

Checkout the guidelines for importing contacts and syncing lists between a local source and Constant Contact.

Import Limitations

There two limitations to be aware of that apply to both the import .csv file and the JSON request payload:

  • File size: the size of the import .csv file or JSON payload must be less than 4 megabytes (MB)
  • Number of contacts: the total number of rows in the import file cannot exceed 40,000 (39,999 contact rows plus a headings row)
When importing a CSV file, contacts in rows above 40,000 are not processed.
If the file size exceeds 4 MB, only the contacts contained in the first 4 MB (and in lines ≤40k) are processed.

About permission_to_send and Imported Contacts

Permission to send signifies the type of relationship an account owner has with a contact. It is important for compliance with US and international anti-spam law. See Constant Contact’s Email Permission Policy for complete information.

When importing contacts:

  • permission_to_send is set to Implicit for all new contacts created in an import activity.
  • permission_to_send is not changed for any existing contacts included in an import activity.
Constant Contact allows customers to import lists of contacts into their account. However, there are rules to be aware of when it comes to what types of email addresses they'll be able send campaigns to.

Importing Contacts from a CSV file

Use the /activities/contacts_file_import multi-part endpoint to import contacts into Constant Contact. The multi-part request has three properties:

  • file - points to the CSV file containing the contact data to import
  • list_ids - an array of list_id values to which the imported contacts will be added
The content-type MUST be unspecified when using this endpoint.

CSV File Content

The import file must be in Comma Separated Value (CSV) format. The CSV file is constructed of columns of contact properties and rows of contacts. It needs to contain at least the email address for each contact. Use the following list of the contact properties for column headings in the CSV file:

  • email - Required; each contact must have an email address or it will not be imported.
  • first_name
  • last_name
  • phone
  • job_title
  • company_name
  • street
  • city
  • state
  • zip
  • country
  • anniversary - Accepts the following formats MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, M-DD-YYYY. The year must be greater than 1900 and cannot be more than 10 years in the future (with respect to the current year).
  • birthday_day - Accepts values from 1-31; Must be used with birthday_month
  • birthday_month - Accepts values from 1-12; Must be used with birthday_day

Importing Contacts Using JSON

Use the /activities/contacts_json_import endpoint to import contacts using a JSON request payload. The JSON request has two properties:

  • import_data - an array of the contact data to import
  • list_ids - an array of up to 50 list_ids to which tthe imported contacts will be added; at least one list_id is required for the import activity to be processed.
The import request will fail if it does not include at least one `list_id`.

JSON Payload Format

These are the properties that can be included for each contact in the import_data section:

property type, required?, maxLength description
anniversary string, optional Accepts the following formats: MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, M-DD-YYYY. The year must be greater than 1900 and cannot be more than 10 years in the future (with respect to the current year).
birthday_day integer, optional Accepts values from 1-31; Must be used with birthday_month
birthday_month integer, optional Accepts values from 1-12; Must be used with birthday_day
city string, optional, Max. Length:50 city in the contact’s address
company_name string, optional, Max. Length:50 name of the contact’s company
country string, optional, Max. Length:50 The contact’s country of residence
email required, string, Max. Length:50 The contact’s email address (must be unique for each contact)
first_name string, optional, Max. Length:50 Yup, the contact’s first name
job_title string, optional, Max. Length:50 Their job title
last_name string, optional, Max. Length:50 The contact’s last (family) name
phone string, optional, Max. Length:50 A phone number for the contact
state string, optional, Max. Length:50 State or province the contact resides in
street string, optional, Max. Length:255 Street address line 1
street2 string, optional, Max. Length:255 Street address line 2, gets appended to street
zip string, optional, Max. Length:50 Zip or postal code

Import JSON Request Sample

GET https://api.cc.email/v3/contacts?updated_after=2017-12-01&include_count=true

<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/activities/contacts_json_import/');
$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('{
  "import_data": [
    {
      "email": "jjones@example.com",
      "first_name": "Joe",
      "last_name": "Jones",
      "job_title": "Chief Innovation Officer",
      "company_name": "RelativeGravity, Inc.",
      "birthday_month": 11,
      "birthday_day": 24,
      "anniversary": "2006-11-15",
      "phone": "555-555-5555",
      "street": "123 Maple Lane",
        "street2": "Apt. 337",
        "city": "Chicago",
      "state": "Illinois",
      "zip": "60609",
      "country": "United States"
    },
    {
      "email": "rdahlia@example.com",
      "first_name": "Roger",
      "last_name": "Dahlia"
    },
    {
      "email": "donny725@test.com"
    },
    {
      "email": "A.test@example.com",
      "first_name": "Anton",
      "last_name": "tester",
      "job_title": "Software Engineer",
      "company_name": "CTCT",
      "create_source": "Contact",
      "birthday_month": 4,
      "birthday_day": 1,
      "anniversary": "04/01/1934"
    },
    {
      "email": "Test.ing@example.com",
      "first_name": "First",
      "last_name": "Last",
      "job_title": "Software Engineer",
      "company_name": "CTCT",
      "create_source": "Contact",
      "birthday_month": 4,
      "birthday_day": 1,
      "anniversary": "04/01/1934"
    }
  ],
  "list_ids": [
    "{list_id1}",
    "{list_id2}",
    "{list_id3}"
  ]
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
curl -X POST \
  https://api.cc.email/v3/activities/contacts_json_import/ \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
-d '{
  "import_data": [
    {
      "email": "jjones@example.com",
      "first_name": "Joe",
      "last_name": "Jones",
      "job_title": "Chief Innovation Officer",
      "company_name": "RelativeGravity, Inc.",
      "birthday_month": 11,
      "birthday_day": 24,
      "anniversary": "2006-11-15",
      "phone": "555-555-5555",
      "street": "123 Maple Lane",
        "street2": "Apt. 337",
        "city": "Chicago",
      "state": "Illinois",
      "zip": "60609",
      "country": "United States"
    },
    {
      "email": "rdahlia@example.com",
      "first_name": "Roger",
      "last_name": "Dahlia"
    },
    {
      "email": "donny725@test.com"
    },
    {
      "email": "A.test@example.com",
      "first_name": "Anton",
      "last_name": "tester",
      "job_title": "Software Engineer",
      "company_name": "CTCT",
      "create_source": "Contact",
      "birthday_month": 4,
      "birthday_day": 1,
      "anniversary": "04/01/1934"
    },
    {
      "email": "Test.ing@example.com",
      "first_name": "First",
      "last_name": "Last",
      "job_title": "Software Engineer",
      "company_name": "CTCT",
      "create_source": "Contact",
      "birthday_month": 4,
      "birthday_day": 1,
      "anniversary": "04/01/1934"
    }
  ],
  "list_ids": [
    "{list_id1}",
    "{list_id2}",
    "{list_id3}"
  ]
}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n\t\"import_data\": [\n\t\t{\n\t\t\t\"email\": \"jjones@example.com\",\n\t\t\t\"first_name\": \"Joe\",\n\t\t\t\"last_name\": \"Jones\",\n\t\t\t\"job_title\": \"Chief Innovation Officer\",\n\t\t\t\"company_name\": \"RelativeGravity, Inc.\",\n\t\t\t\"birthday_month\": 11,\n\t\t\t\"birthday_day\": 24,\n\t\t\t\"anniversary\": \"2006-11-15\",\n\t\t\t\"phone\": \"555-555-5555\",\n\t\t\t\"street\": \"123 Maple Lane\",\n\t\t    \"street2\": \"Apt. 337\",\n\t\t    \"city\": \"Chicago\",\n\t\t\t\"state\": \"Illinois\",\n\t\t\t\"zip\": \"60609\",\n\t\t\t\"country\": \"United States\"\n\t\t},\n\t\t{\n\t\t\t\"email\": \"rdahlia@example.com\",\n\t\t\t\"first_name\": \"Roger\",\n\t\t\t\"last_name\": \"Dahlia\"\n\t\t},\n\t\t{\n\t\t\t\"email\": \"donny725@test.com\"\n\t\t},\n\t\t{\n\t\t\t\"email\": \"A.test@example.com\",\n\t\t\t\"first_name\": \"Anton\",\n\t\t\t\"last_name\": \"tester\",\n\t\t\t\"job_title\": \"Software Engineer\",\n\t\t\t\"company_name\": \"CTCT\",\n\t\t\t\"create_source\": \"Contact\",\n\t\t\t\"birthday_month\": 4,\n\t\t\t\"birthday_day\": 1,\n\t\t\t\"anniversary\": \"04/01/1934\"\n\t\t},\n\t\t{\n\t\t\t\"email\": \"Test.ing@example.com\",\n\t\t\t\"first_name\": \"First\",\n\t\t\t\"last_name\": \"Last\",\n\t\t\t\"job_title\": \"Software Engineer\",\n\t\t\t\"company_name\": \"CTCT\",\n\t\t\t\"create_source\": \"Contact\",\n\t\t\t\"birthday_month\": 4,\n\t\t\t\"birthday_day\": 1,\n\t\t\t\"anniversary\": \"04/01/1934\"\n\t\t}\n\t],\n\t\"list_ids\": [\n\t\t\"{list_id1}\",\n\t\t\"{list_id2}\",\n\t\t\"{list_id3}\"\n\t]\n}");
Request request = new Request.Builder()
  .url("https://api.cc.email/v3/activities/contacts_json_import/")
  .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

{
    "activity_id": "{activity_id}",
    "state": "initialized",
    "created_at": "2018-02-23T11:55:42-05:00",
    "updated_at": "2018-02-23T11:55:42-05:00",
    "source_file_name": "csv_from_json_2018-02-23T11_55_42-05_0020180223-13361-eo9aca.csv",
    "percent_done": 1,
    "activity_errors": [],
    "status": {},
    "_links": {
        "self": {
            "href": "/v3/activities/{activity_id}"
        }
    }
}

Checking the Activity Status for Job Complete

Check on the status of the JSON Import activity by calling the link to the activity status provided in the _links section of the response. The activity_id for your request is provided in the href link. To retrieve the status, make the following GET call:

GET https://api.cc.email/v3/activities/{activity_id}