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

You can import contacts from another source into a Constant Contact account using a CSV payload or a JSON payload. The CSV import endpoint is POST /activities/contacts_file_import. The JSON import endpoint is POST /activities/contacts_json_import.

You can use these endpoints to import new contacts and update existing contacts when syncing local data with Constant Contact. These endpoints use the email addresses you provide in the import to determine if each contact is new or not. When you import an existing contact, these endpoints only update the contact properties you include in the import request.

For more information on syncing contact data, see the Guidelines for Importing Contacts.

Import Limitations

The following limitations apply to the import methods:

  • File size: The size of the imported CSV file or JSON payload must be less than 4 megabytes (MB).
  • Number of contacts: The total number of rows in the CSV import file cannot exceed 40,000 (39,999 contact rows plus a headings row). The total number of contacts in the JSON payload cannot exceed 40,000.
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.

Import Contacts from a CSV file

Make a POST call to the /activities/contacts_file_import multipart/form-data endpoint to import contacts into Constant Contact using a CSV file. This method requires a multipart/form-data request body that contains the file and list_ids properties.

  • file - The contacts you are importing as a CSV file containing contact data.
  • list_ids - The contact lists you want to add all imported contacts to as an array of contact list_id values. You must include at least one list_id value and cannot include more than 50 list_id values.
The content-type MUST be unspecified when using this endpoint.

CSV File Content

The import file must be in comma-separated value (CSV) format. Create the CSV file adding contact properties to the CSV header and your contact data as rows in the CSV. You can also include custom fields in the CSV file. The CSV file must contain an email header. This method identifies each unique contact using their email address.

You can use the following contact properties in the CSV file:

Header Column Name Column Attributes Description
first_name optional, Max. Length:50 The first name of the contact.
last_name optional, Max. Length:50 The last name of the contact.
job_title optional, Max. Length:50 The job title of the contact.
company_name optional, Max. Length:50 The name of the company where the contact works.
anniversary optional The anniversary date for the contact. For example, this value could be the date when the contact first became a customer of an organization in Constant Contact. Valid date formats are MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, or 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_month optional, minimum 1, maximum 12 The month value for the contact’s birthday. Valid values are from 1 through 12. You must use this column with birthday_day.
birthday_day optional, minimum 1, maximum 31 The day value for the contact’s birthday. Valid values are from 1 through 31. You must use this column with birthday_month.
phone optional, Max. Length:50 The phone number for the contact.
street optional, Max. Length:255 Line one of the street address for the contact.
street2 optional, Max. Length:255 Line two of the street address for the contact. This value is automatically appended to the street value.
city optional, Max. Length:50 The name of the city where the contact lives.
state optional, Max. Length:50 The name of the state or province where the contact lives.
zip optional, Max. Length:50 A zip or postal code for the contact.
country optional, Max. Length:50 The name of the country where the contact lives.
cf:custom_field_name optional, Max. Length:255 This header column name is the name of an existing custom field prefixed with cf:. For example, enter cf:first_name if you have a custom field named “first_name”. As long as you use the cf: prefix, you can import custom fields that use the same name as the contact properties. You can add up to 25 different custom field headings for each contact.

CSV File Example

Click here to download an example CSV file.

In order to import custom field data, the custom fields must already exist in the Constant Contact account you are using. The example file uses custom fields named "first_name" and "vehicle_make_and_model_year".

Import Contacts Using JSON

Make a POST call to the /activities/contacts_json_import endpoint to import contacts using a JSON request payload. This method requires a JSON request body that contains the import_data and list_ids arrays.

  • import_data - The contacts you are importing as an array of objects containing contact data.

  • list_ids - The contact lists you want to add all imported contacts to as an array of contact list_id strings. You must include at least one list_id value and cannot include more than 50 list_id values.

Contact Import Data Format

You can use the following contact properties with each object in the import_data array:

Property Name Property Attributes Description
email required, string, Max. Length:50 The email address of the contact. This method identifies each unique contact using their email address.
first_name string, optional, Max. Length:50 The first name of the contact.
last_name string, optional, Max. Length:50 The last name of the contact.
job_title string, optional, Max. Length:50 The job title of the contact.
company_name string, optional, Max. Length:50 The name of the company where the contact works.
anniversary string, optional, The anniversary date for the contact. For example, this value could be the date when the contact first became a customer of an organization in Constant Contact. Valid date formats are MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, or 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_month integer, minimum 1, maximum 12, optional The month value for the contact’s birthday. Valid values are from 1 through 12. You must use this property with birthday_day.
birthday_day integer, minimum 1, maximum 31, optional The day value for the contact’s birthday. Valid values are from 1 through 31. You must use this property with birthday_month.
phone string, required, Max. Length:50 The primary phone number for the contact. Default type = home
home_phone string, optional, Max. Length:50 The home phone number for the contact. Type = home
work_phone string, optional, Max. Length:50 The work phone number for the contact. Type = work
other_phone string, optional, Max. Length:50 Another phone number for the contact. Type = other
street string, optional, Max. Length:255 Line one of the street address for the contact. Default, type = home
street2 string, optional, Max. Length:255 Line two of the street address for the contact. This value is automatically appended to the street value. Default, type = home
other_street string, optional, Max. Length:255 Line one of the another street address for the contact. Type = other
other_street2 string, optional, Max. Length:255 Line two of the other street address for the contact. This value is automatically appended to the other_street value. Type = other
home_street string, optional, Max. Length:255 Line one of the home street address for the contact. Type = home
home_street2 string, optional, Max. Length:255 Line two of the street address for the contact. This value is automatically appended to the home_street value. Default type = home
work_street string, optional, Max. Length:255 Line one of the work street address for the contact. Type = work
work_street2 string, optional, Max. Length:255 Line two of the street address for the contact. This value is automatically appended to the work_street value. Type = work
city string, optional, Max. Length:50 The primary city name for the contact. Default, type home
home_city string, optional, Max. Length:50 The name of the city where the contact lives. Type = home
work_city string, optional, Max. Length:50 The name of the city where the contact works. Type = work
other_city string, optional, Max. Length:50 The name of another city where the contact is located. Type = other
state string, optional, Max. Length:50 The primary name of the state or province for the contact. Default type = home
other_state string, optional, Max. Length:50 Another name of a state or province for the contact. Type = other
home_state string, optional, Max. Length:50 The name of the home state or province where the contact lives. Type = home
work_state string, optional, Max. Length:50 The name of another state or province where the contact works. Type = work
zip string, optional, Max. Length:50 The primary zip or postal code for the contact. Default, type = home
home_zip string, optional, Max. Length:50 A zip or postal code for where the contact’s home is located. Type = home
work_zip string, optional, Max. Length:50 A zip or postal code for where the contact’s works. Type = work
other_zip string, optional, Max. Length:50 A zip or postal code for another location where the contact is located. Type = other
country string, optional, Max. Length:50 The name of the country where the contact lives. Default, type = home
home_country string, optional, Max. Length:50 The name of the country where the contact lives. Type = home
work_country string, optional, Max. Length:50 The name of the country where the contact works. Type = work
other_country string, optional, Max. Length:50 Another name of the country where the contact is located. Type = other
cf:custom_field_name string, optional, Max. Length:255 A contact custom field. The name of this property is dynamic based on the custom fields that you want to import. Use a key-value pair where the key is an existing custom field name prefixed with cf:, and the value is a custom field string value. As long as you use the cf: prefix, you can import custom fields that use the same name as the contact properties. You can import up to 25 custom fields in each contact.

Import JSON Request Sample

POST https://api.cc.email/v3/activities/contacts_json_import

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

<?php

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

$request->setHeaders(array(
  'Postman-Token' => '23afb38f-650d-4e5c-9eac-798f2a6a10e2',
  '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": "556-555-5555",
      "street": "123 Maple Lane",
      "street2": "Apt. 337",
      "zip": "60609",
      "country": "United States",
      "cf:first_name": "Joey",
      "cf:vehicle_make_and_model_year": "Tesla S 2017"
    },
    {
      "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/2014",
      "cf:vehicle_make_and_model_year": "Honda Ridgeline Sport 2014"
    }
  ],
  "list_ids": [
    "2e73c594-78be-11e9-bfd0-fa163e6b01c1","3a192c16-5ade-11e9-a67b-fa163e6b01c1"
  ]
}');

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 'Content-Type: application/json' \
  -H 'Postman-Token: 188daafb-9ee2-4380-9010-e7f3b4c45e56' \
  -H 'cache-control: no-cache' \
  -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": "556-555-5555",
      "street": "123 Maple Lane",
      "street2": "Apt. 337",
      "zip": "60609",
      "country": "United States",
      "cf:first_name": "Joey",
      "cf:vehicle_make_and_model_year": "Tesla S 2017"
    },
    {
      "email": "A.test@example.com",
      "first_name": "Anton",
      "last_name": "Smith",
      "job_title": "Software Engineer",
      "company_name": "RelativeGravity, Inc.",
      "birthday_month": 4,
      "birthday_day": 1,
      "anniversary": "04/01/2014",
      "cf:vehicle_make_and_model_year": "Honda Ridgeline Sport 2014"
    }
  ],
  "list_ids": [
    "2e73c594-78be-11e9-bfd0-fa163e6b01c1","3a192c16-5ade-11e9-a67b-fa163e6b01c1"
  ]
}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"import_data\": [\n    {\n      \"email\": \"jjones@example.com\",\n      \"first_name\": \"Joe\",\n      \"last_name\": \"Jones\",\n      \"job_title\": \"Chief Innovation Officer\",\n      \"company_name\": \"RelativeGravity, Inc.\",\n      \"birthday_month\": 11,\n      \"birthday_day\": 24,\n      \"anniversary\": \"2006-11-15\",\n      \"phone\": \"556-555-5555\",\n      \"street\": \"123 Maple Lane\",\n      \"street2\": \"Apt. 337\",\n      \"zip\": \"60609\",\n      \"country\": \"United States\",\n      \"cf:first_name\": \"Joey\",\n      \"cf:vehicle_make_and_model_year\": \"Tesla S 2017\"\n    },\n    {\n      \"email\": \"A.test@example.com\",\n      \"first_name\": \"Anton\",\n      \"last_name\": \"tester\",\n      \"job_title\": \"Software Engineer\",\n      \"company_name\": \"CTCT\",\n      \"create_source\": \"Contact\",\n      \"birthday_month\": 4,\n      \"birthday_day\": 1,\n      \"anniversary\": \"04/01/2014\",\n      \"cf:vehicle_make_and_model_year\": \"Honda Ridgeline Sport 2014\"\n    }\n  ],\n  \"list_ids\": [\n    \"2e73c594-78be-11e9-bfd0-fa163e6b01c1\",\"3a192c16-5ade-11e9-a67b-fa163e6b01c1\"\n  ]\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")
  .addHeader("Postman-Token", "b95d402e-93a7-466d-8dbb-db1afb91a7f2")
  .build();

Response response = client.newCall(request).execute();

Response

{
    "activity_id": "3c472a68-8218-11e9-b1a7-fa163e56c9b0",
    "state": "initialized",
    "created_at": "2019-05-29T09:47:01-04:00",
    "updated_at": "2019-05-29T09:47:01-04:00",
    "source_file_name": "csv_from_json_2019-05-29T09_47_01-04_0020190529-31124-1mhsxhe.csv",
    "percent_done": 1,
    "activity_errors": [],
    "status": {},
    "_links": {
        "self": {
            "href": "/v3/activities/3c472a68-8218-11e9-b1a7-fa163e56c9b0"
        }
    }
}

Checking the Activity Status for Job Complete

After you send an import request, the V3 API returns a response body that includes an activity_id and the current status of the import activity. Send a GET request to the /activities/{activity_id} endpoint endpoint to determine when the V3 API has finished importing your contacts. You can also use the URL that the V3 API returns in the href response body property to send the request.

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

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

Try it!