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, defined in the Structure section below. 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

429

We cannot complete your request because you have too many requests in progress.

500

Internal server error occurred

StructureTOP

property

type(max length)

description

data

string

REQUIRED. Part of the multipart requestbody, it's the data contained in the file being uploaded

file_name

string

REQUIRED. Part of the multipart requestbody, its the name of the file that contains the contact information to import

lists

string

REQUIRED. Part of the multipart requestbody, this is a comma separated list of contact list Ids specifying the contact lists to which the contacts are to be added

Response StructureTOP

property

type(max length)

description

contact_count

string

Displays the number of contacts that were processed, and is meaningful only after the activity is completed; the value is not predictable if the activity has not yet been processed. (Read Only)

error_count

string

Displays the number of errors encountered, and is meaningful only after the activity is completed; the value is not predeictable if the activity has not yet been processed. (Read Only)

id

string

Unique ID for the activity (Read Only)

type

string

ADD_CONTACTS - add the contacts to contact list(s) specified in the import file or JSON payload (Read Only)

Example ResponseTOP

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