Our v3 API is now available! Learn more by visiting the v3 developer portal. Creating new v2 API keys is no longer supported.

Bulk Activities - Import Contacts Multipart Endpoint

Use this endpoint to create an asynchronous background job to import contacts and any associated properties in binary form using the multipart content-type. CSV files are currently the only supported file type.

Methods:

Click a method to view its documentation

POST

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.

POST: https://api.constantcontact.com/v2/activities/addcontacts

Response CodesTOP

code

description

201

Request was successful and is queued for processing

400

Bad Request; Error in validating a contact

401

Authentication failure

500

Internal server error occurred

StructureTOP

property

type(max length)

description

Response StructureTOP

property

type(max length)

description

Example ResponseTOP

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