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.  

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.

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

name

type

default

description

api_key

query

REQUIRED; The API key for the application

Example JSON Request BodyTOP

{
    "import_data": [{
        "email_addresses": [
            "user1@example.com"
        ],
        "first_name": "John",
        "last_name": "Smith",
        "birthday_month":"1",
        "birthday_day":"25",
        "anniversary":"03/12/2005",
        "job_title": "",
        "company_name": "My Company",
        "home_phone": "5555551212",
        "addresses": [{
            "line1": "123 Partridge Lane",
            "line2": "Apt. 3",
            "city": "Anytown",
            "address_type": "PERSONAL",
            "state_code": "NH",
            "country_code": "US",
            "postal_code": "02145"
        }]
    },
    {
        "email_addresses": [
            "user2@example.com"
        ],
        "first_name": "Jane",
        "last_name": "Doe",
        "job_title": "",
        "company_name": "Acme, Inc.",
        "home_phone": "5555551213",
        "addresses": [{
            "line1": "456 Jones Road",
            "city": "AnyTownShip",
            "address_type": "PERSONAL",
            "state_code": "DE",
            "country_code": "US",
            "postal_code": "01234"
        }],
        "custom_fields": [{
            "name": "Custom Field 6",
            "value": "Blue Jeans"
        }, {
            "name": "Custom Field 12",
            "value": "Special Order"
        }]
    }, {
        "email_addresses": [
            "user3@example.com"
        ],
        "first_name": "Pradeep",
        "last_name": "Patel",
        "job_title": "",
        "company_name": "Acme Movers",
        "home_phone": "5555551214"
    }],
    "lists": [
        "4",
        "5",
        "6"
    ],
    "column_names": [
        "EMAIL",
        "FIRST NAME",
        "LAST NAME",
        "ADDRESS LINE 1",
        "ADDRESS LINE 2",
        "CITY",
        "STATE",
        "COUNTRY",
        "Zip/Postal Code",
        "JOB TITLE",
        "COMPANY NAME",
        "HOME PHONE",
        "Custom Field 6",
        "Custom Field 12"
    ]
}

Response CodesTOP

code

description

201

Request was successful

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

column_names

array

REQUIRED. Specifies the contact properties (column names) to include with each contact you're adding or updating. Valid column names listed here are not case sensitive:

  • EMAIL
  • FIRST NAME
  • LAST NAME
  • BIRTHDAY_DAY - 1 to 31
  • BIRTHDAY_MONTH - 1 to 12
  • ANNIVERSARY - Accepts the following formats MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, M-DD-YYYY. The year must be greater than 1900 and cannot be more than 10 years in the future (with respect to the current year).
  • JOB TITLE
  • COMPANY NAME
  • WORK PHONE
  • HOME PHONE
  • ADDRESS LINE 1,2
  • CITY
  • STATE
  • COUNTRY
  • ZIP/POSTAL CODE
  • CUSTOM FIELD 1 (to 15)

+ import_data

array

REQUIRED. Import data

lists

array

REQUIRED. An array of listIds specifying to which lists to add the contacts

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 until the activity is complete. (Read Only)

error_count

string

Displays the number of errors encountered, and is meaningful only after the activity is completed; the value is not predictable until the activity is complete. (Read Only)

id

string

Unique ID for the activity (Read Only)

type

string

ADD_CONTACTS - add 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
}