DescriptionTOP

Privileges required: contacts:write

You can add contacts to a user's Constant Contact account by importing a file containing the contact information. Use an HTTP multipart request in a POST to this endpoint. The multipart request contains three parameters: file_name, lists, and data as defined in the Structure section below.

By default, importing contact information that includes blank fields does not erase (clear) the contacts current information. To erase existing contact properties, include the blanks_enabled query parameter in the path and set it to true (&blanks_enabled=true).

The file with the contact information must contain at least the email addresses for the contacts being imported.

NOTE: Set the Content-Type header to multipart/form-data.

Import File Content

The import file is constructed of columns containing contact properties, with rows for each contact. It needs to contain at least the email address for each contact. The following is a list of the contact properties (column headings in a spreadsheet) that can be included in the import file (these are not case sensitive):

• Email address
• First Name
• Last Name
• Birthday_Day
• Birthday_Month
• Anniversary - Use one of the following formats: MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D, M-D-YYYY, MM-DD-YYYY. The year must be greater than 1900 or 00, and cannot be more than 10 years in the future.
• Job Title
• Company Name
• Work Phone
• Home Phone
• Address Line 1 (to 3)
• City
• State
• Country
• Zip/Postal Code
• Custom Field 1 (to 15)

NOTE: For Import Contacts bulk activities only, the state field is a 50 character free-form text field. 

Deprecated column_names

The following columns have been deprecated as of the May 5, 2014 update:

• SUB ZIP/POSTAL CODE
• MIDDLE NAME
• US STATE/CA PROVINCE

Existing integrations using these column names will not return errors, but the API ignores these columns and any values. 

Limitations

The size of the request payload (import file) must be less than 4 megabytes. Also, the  number of contacts that you can import in a single POST is limited to 40,000. The activity request will fail if the payload is greater than 4 MBs or if there are more 40,000 contacts. Remember, the more columns or properties that you include with the imported contact, the bigger the request payload will be.

Java example

Here's an example of a multipart encoded post written in Java that adds contacts to contact list 1 (listId=1) by importing a file (contacts.txt):

final HttpClient httpclient = new DefaultHttpClient();
   final HttpPost httppost = new HttpPost("https://api.constantcontact.com/v2/activities/addcontacts");

   httppost.addHeader("Authorization", "Bearer 5e35af38-7b63-47cac-b484-20c4ff4d09c8");
   httppost.addHeader("Accept", ”application/json”);
   httppost.addHeader("content-type", "multipart/form-data");

   final File fileToUse = new File("/path_to_file/contacts.txt");  //e.g. /temp/contact.txt
   final FileBody data = new FileBody(fileToUse);
   final String listIds = "1";
   final StringBody lists = new StringBody(listIds);
   final StringBody fileName = new StringBody(fileToUse.getName());
   final MultipartEntity reqEntity = new MultipartEntity();
   reqEntity.addPart("file_name", fileName);
   reqEntity.addPart("lists", lists);
   reqEntity.addPart("data", data);

   httppost.setEntity(reqEntity);

   final HttpResponse response = httpclient.execute(httppost);
   final HttpEntity resEntity = response.getEntity();

   EntityUtils.consume(resEntity);

  httpclient.getConnectionManager().shutdown();
}

Ruby example

See a Ruby example in our Github respository here.

Activity Status

To see the status of an activity, make a GET call to the URI returned in the response's location header:

Location: https://api.constantcontact.com/v2/activities/<activity_id> 

Poll this URI to monitor the activity status until the status is either COMPLETE or ERROR, indicating that the activity has completed processing. The response structure for this GET call is detailed here.

See also Summary Activity Reports endpoint.

Response CodesTOP

StructureTOP

Response StructureTOP

Example ResponseTOP

{
"id": "a07e1il97e1hddalkpk",
"type": "ADD_CONTACTS",
"error_count": 0,
"contact_count": 3
}