Our v3 API is now available! Learn more by visiting the v3 developer portal.

Bulk Activities - Import Contacts Endpoint

Constant Contact encourages the use of asynchronous background jobs to manage large collections of data as a best practice. Use the Bulk Activity endpoints to create asynchronous background jobs (activities). Use this bulk activity endpoint to create an asynchronous background job that adds new or existing contacts to one or more contact lists.

Methods:

Click a method to view its documentation

POST

DescriptionTOP

Privileges required: contacts:write

This endpoint lets you add or update multiple contacts with a single API call using a JSON payload that includes the contacts, contact properties, and contact lists as described here.

import_data Array

In the JSON payload, contacts are identified by their email address in an import_data array (see the JSON Request example). If a contact in the array already exists in the user's account, the properties included in the request are updated, and any existing properties not included in the import are not changed (action is an update only, not a PUT, so no property values are erased if left blank). You only need to include an email address to add a contact, but you can include additional contact properties in import_data. Any additional properties need to be declared in the column_names array.

NOTE: For bulk imports only, the state_code field is an 50 character free-form text input field.  

NOTE: Only 1 email address is allowed per contact. 

column_names Array

The column_names array lists the contact properties that you are including with the contacts. See the JSON Structure table below for valid column names to use. Any properties not listed in column_names are ignored and not added with the contacts. You must include a column_names array even if it is empty. If it is empty, and the first contact in import_data has a valid email address, the activity will proceed, but only the email addresses are added, and all other properties are ignored. If the first contact does not have a valid email address, then the request fails and no contacts are added or updated. If column_names is non-empty, it must include EMAIL, or the activity will fail.

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 along with any values in the imported data. 

lists Array

You specify which contact lists to add the contacts to in the lists array (see the JSON Request example). You must specify at least one listId in lists, or the activity request will fail. If a listId in the array does not exist in the user's account, the activity request will fail.

JSON Payload Limitations

The size of the JSON request payload 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 JSON payload will be.

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 API

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

Example JSON Request BodyTOP


Example ResponseTOP