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 by default, no property values are erased if left blank). To erase existing contact properties, include the blanks_enabled query parameter in the path and set it to true (&blanks_enabled=true).  

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

DescriptionTOP

Privileges required: contacts:write

Export the members of a contact list to a RFC 4180 compliant .CSV file. In the JSON request body you need to specify the following properties:

• lists array
• file_type
• sort_by
• export_date_added
• export_added_by
• column_names

See the Structure section for details and values for these properties.

column_names array

The column_names array lists the contact properties to include in the exported file. See the JSON Structure table below for valid column names to use. If the first contact does not have a valid email address, then the request fails and no contacts are exported. "Email" must be included in column_names, or the activity will fail.  

Deprecated column_names

The following columns names have been deprecated for export 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.

Export system generated lists

You can export the following system generated contact lists that are filtered by contact status by specifying them as follows in the lists array (include only a single list in the array):

• active
• opted-out
• removed

View contact status definitions here.

Activity status

You can poll the URI returned in the response's location header to monitor the status of the export activity. You must include the access_token and api_key when making a GET call to the activity status report endpoint:

https://api.constantcontact.com/v2/activities/<activity_id>?api_key=<api_key>

The activity has finished once the status is returned as either COMPLETE or ERROR. The activity status response structure is detailed here. 

How to get the exported file

Once the activity completes processing (status = COMPLETE or ERROR in the activity status report), the status report will also include the file_name property, which is the URL where the file is hosted. The value of this property is a URI that points to the location of the exported file. To retrieve the file, make a GET call to the URI, be sure to include the access_token and api_key in the call. 

GET <file_name>?api_key=<api_key>

DescriptionTOP

Privileges required: contacts:write

This endpoint removes the contacts specified by email address in import_data from the contact lists defined in the lists array. You need to construct the JSON request payload that contains the contacts and the contact lists they will be removed from. See the JSON Request example for details on constructing the request.

Limitations

The size of the JSON request payload must be less than 4 megabytes. Also, the number of contacts that you can remove in a single POST is limited to 20,000. The activity request will fail if the payload is greater than 4 MBs or if it contains more 20,000 email addresses.

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: Bulk Activity Summary Reports

DescriptionTOP

Privileges required: contacts:write

This endpoint clears (removes) all contacts from the contact list specified by listId in the lists array in the JSON request body. See the example JSON Request below for details on constructing the JSON payload.

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

Example JSON Request BodyTOP

{
   "lists":[
    "2",
    "3"
  ]
}

Response CodesTOP

StructureTOP

Response StructureTOP

Example ResponseTOP

{
"id": "a07e1il97rdhddlqqv9",
"type": "CLEAR_CONTACTS_FROM_LISTS",
"error_count": 0,
"contact_count": 627
}