Bulk Activities - Remove Contacts Endpoint

Use this endpoint to create asynchronous background jobs that remove contacts from one or more contact lists.

Methods:

Click a method to view its documentation

POST

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

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

name

type

default

description

api_key

query

REQUIRED; The API key for the application

Example JSON Request BodyTOP

{
   "import_data":[
    {
        "email_addresses":[
          "my_email@example.com"
        ]
    },
    {
        "email_addresses":[
          "your_email@example.com"
        ]
    }
   ],
  "lists":[
    "4",
    "5",
    "6"
  ]
}

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

+ import_data

array

REQUIRED. Import data

lists

array

REQUIRED. An array of listIds specifying which contact lists to remove the contacts from

Response StructureTOP

property

type(max length)

description

contact_count

string

Displays the number of contacts that were processed after the activity is completed. (Read Only)

error_count

string

Displays the number of errors encountered in processing the activity after it is completed. (Read Only)

id

string

Unique ID for the activity (Read Only)

type

string

REMOVE_CONTACT_FROM_LISTS - remove the contacts from the list(s), all specified in the import file (Read Only)

Example ResponseTOP

{
"id": "a07e1il97jehddh1z8x",
"type": "REMOVE_CONTACTS_FROM_LISTS",
"error_count": 0,
"contact_count": 2
}