Bulk Activities

Import Contacts using a CSV File

Changed on

This multipart method creates an asynchronous background job that adds or updates contacts by importing a CSV file containing contact information. Do not use a Content-Type header value with this method.

Importing a new contact email address automatically sets the contact's permission_to_send property as implicit and the opt_in_source property as Account. Importing an existing contact only updates the contact properties you include in the request. Importing contacts with sms_numbers requires using the sms_permission_to_send parameter to specify permissions for all contacts being imported. Set to explicit to specify that all contacts either provided explicit permission. Set to not_set if permission was not provided. If explicit, you must also include the sms_consent_date as a column header to include the date the contact consented to receiving SMS messages. Contacts must have either an email address or an SMS number defined.

The CSV file has a maximum of 40,000 lines including the header row (39,999 contacts) and a maximum file size of 4 megabytes (MB). Lines above the 40,000 line maximum are not processed. If the request body exceeds 4 MB, only the contacts contained in the first 4 MB are imported and the remaining data is dropped.

post/activities/contacts_file_import

Request

  • Base URL
    https://api.cc.email/v3
  • URL
    https://api.cc.email/v3/activities/contacts_file_import
  • Auth
    • OAuth 2
      Implicit: https://authz.constantcontact.com/oauth2/default/v1/authorize
      Scopes: contact_data
    • or OAuth 2
      Authorization code: https://authz.constantcontact.com/oauth2/default/v1/authorize
      Token URL: https://authz.constantcontact.com/oauth2/default/v1/token scopes: contact_data

Request body multipart/form-data

filestring binary required

The CSV file you are importing must include either email or sms_number as a column heading. Other properties you can include using column headings are: first_name. last_name, phone, job_title, anniversary, birthday_day, birthday_month, company_name, street, street2, city, state, zip, country, and sms_consent_date.

If adding an sms_number, you must also include the sms_permission_to_send parameter and set it to either not_set or explicit. If explicit, requires including sms_consent_date as a column header to specify the date the contact consented to receiving SMS messages.

You can also use custom fields as column headings. Enter the custom field name prefixed with cf: as the column heading. For example, use cf:first_name as the header name if you have a custom field named "first_name". The custom field must already exist in the Constant Contact account you are using. Depending on the custom field data type, you can enter dates or strings as the value of the custom field. Each contact can contain up to 25 different custom fields.

list_idsstring csv required

Specify which contact lists you are adding all imported contacts to as an array of up to 50 contact list_id values.

sms_permission_to_send'not_set' | 'explicit'

If importing contact sms_numbers, use this parameter to specify how SMS consent was provided. If all contacts in the file provided their consent, set to explicit and include each contact's sms_consent_date. If all contacts in the file have not yet provided consent, set to not_set (sms_consent_date is not required). You cannot message a contact that does not have a sms consent date set.

Example request

{
  "file": "new_contacts_import.csv",
  "list_ids": "8c077f20-1586-11e4-bcb3-00163e56be7c",
  "sms_permission_to_send": "not_set"
}

Response

Request successful. Activity queued for processing.

activity_idstring uuid

Unique ID for the activity.

statestring

The state of the request:

<p><ul> <li>initialized - request has been received</li> <li>processing - request is being processed</li> <li>completed - job completed</li> <li>cancelled - request was cancelled</li> <li>failed - job failed to complete</li> <li>timed_out - the request timed out before completing"</li> </ul> </p>
started_atstring date-time

Timestamp showing when we began processing the activity request, in ISO-8601 format.

completed_atstring date-time

Timestamp showing when we completed processing the activity, in ISO-8601 format.

created_atstring date-time

Timestamp showing when we created the activity, in ISO-8601 format.

updated_atstring date-time

Timestamp showing when we last updated the activity, in ISO-8601 format.

source_file_namestring

Name of the file used for an file_import activity.

percent_doneinteger

Shows the percent done for an activity that we are still processing.

activity_errorsstring[]

Array of messages describing the errors that occurred.

Example response

{
  "activity_id": "86b90820-cc52-11ea-9dad-fa163e3d9194",
  "state": "initialized",
  "started_at": "2016-01-23T13:48:40.108Z",
  "completed_at": "2016-01-23T13:48:44.108Z",
  "created_at": "2016-01-23T13:48:44.108Z",
  "updated_at": "2016-01-23T13:48:44.108Z",
  "source_file_name": "2016-21-04-contact_import.xls",
  "percent_done": 75,
  "activity_errors": [
    "Message describing the error condition."
  ],
  "status": {
    "items_total_count": 87,
    "person_count": 20,
    "error_count": 1,
    "correctable_count": 1,
    "cannot_add_to_list_count": 1
  },
  "_links": {
    "self": {
      "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
    }
  }
}

Changes