How to delete large numbers of contacts using the /contact_delete activity endpoint

Use the /activities/contact_delete endpoint to delete large numbers of contacts in an account. This endpoint allows you to specify the contacts to delete in one of two mutually exclusive ways:

  • either by contact_id - you can specify up to 500 individual contacts
  • or by list_id - delete all the contacts that are members of up to 50 lists

Learn more about deleted contacts.

JSON Request Payload

The JSON request payload consists of an array of either contact_ids or list_ids.

This example deletes all contacts that are members of the lists specified in the list_ids array.

POST /activities/contact_delete

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

{
  "list_ids": [
	"960a7193-7348-499d-ab05-9e8378283798",
	"9ef9d8fe-e0b9-419d-b845-fc4e76aa6a2c",
	"0f0af4ad-c2b2-4cd8-bb87-ce59dc7f669f",
	"29208b05-3a01-4a11-b35c-f3e875b6d42f",
	"61476c97-b57e-4e73-8f46-dfa9f7ab7b85",
	"4d6ff004-a18c-4def-807d-7ee73b53bd89",
	"97353b5c-6714-4dea-939e-e81017a7e0a8",
	"e184fe62-efa2-4d4d-8286-598fb75877a7"
    ]
}

Similarly, if you specify contacts to delete by contact_id, the payload is an array of up to 500 contact_ids.

POST /activities/contact_delete

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

{
  "contact_ids": [
	"e184fe62-7348-499d-ab05-9e8378283798",
	"9ef9d8fe-e0b9-419d-b845-fc4e76aa6a2c",
	"0f0af4ad-c2b2-4cd8-bb87-ce59dc7f669f",
	"29208b05-3a01-4a11-b35c-f3e875b6d42f",
	"47521c97-b57e-4e73-8f46-dfa9f7ab7b85",
	"56ad9004-4dea-4def-807d-7ee73b53bd89",
	"97353b5c-6714-a18c-939e-e81017a7e0a8",
	"960a4257-efa2-4d4d-8286-598fb75877a7"
    ]
}

Example Request

POST https://api.cc.email/v3/contacts

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

<?php

$request = new HttpRequest();
$request->setUrl('https://api.cc.email/v3/activities/contact_delete');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'cache-control' => 'no-cache',
  'authorization' => 'Bearer {access_token}',
  'content-type' => 'application/json',
));

$request->setBody('{
  "list_ids": [
    "960a7193-7348-499d-ab05-9e8378283798",
	"9ef9d8fe-e0b9-419d-b845-fc4e76aa6a2c",
	"0f0af4ad-c2b2-4cd8-bb87-ce59dc7f669f",
	"29208b05-3a01-4a11-b35c-f3e875b6d42f",
	"61476c97-b57e-4e73-8f46-dfa9f7ab7b85",
	"4d6ff004-a18c-4def-807d-7ee73b53bd89",
	"97353b5c-6714-4dea-939e-e81017a7e0a8",
	"e184fe62-efa2-4d4d-8286-598fb75877a7"
  ]
}');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}
curl -X POST \
  https://api.cc.email/v3/activities/contact_delete \
  -H 'authorization: Bearer {access_token}' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
  "list_ids": [
    "960a7193-7348-499d-ab05-9e8378283798",
	"9ef9d8fe-e0b9-419d-b845-fc4e76aa6a2c",
	"0f0af4ad-c2b2-4cd8-bb87-ce59dc7f669f",
	"29208b05-3a01-4a11-b35c-f3e875b6d42f",
	"61476c97-b57e-4e73-8f46-dfa9f7ab7b85",
	"4d6ff004-a18c-4def-807d-7ee73b53bd89",
	"97353b5c-6714-4dea-939e-e81017a7e0a8",
	"e184fe62-efa2-4d4d-8286-598fb75877a7"
  ]
}'
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"list_ids\": [\r\n    \"960a7193-7348-499d-ab05-9e8378283798\",\r\n\t\"9ef9d8fe-e0b9-419d-b845-fc4e76aa6a2c\",\r\n\t\"0f0af4ad-c2b2-4cd8-bb87-ce59dc7f669f\",\r\n\t\"29208b05-3a01-4a11-b35c-f3e875b6d42f\",\r\n\t\"61476c97-b57e-4e73-8f46-dfa9f7ab7b85\",\r\n\t\"4d6ff004-a18c-4def-807d-7ee73b53bd89\",\r\n\t\"97353b5c-6714-4dea-939e-e81017a7e0a8\",\r\n\t\"e184fe62-efa2-4d4d-8286-598fb75877a7\"\r\n  ]\r\n}");
Request request = new Request.Builder()
  .url("https://api.cc.email/v3/activities/contact_delete")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Bearer {access_token}")
  .addHeader("cache-control", "no-cache")
  .build();

Response response = client.newCall(request).execute();

Response

Delete Contacts requests are handled asynchronously, and the response provides a link to the activity status where you can check on the results.

{
    "activity_id": "993d7bc0-c3e5-11e7-a1be-90b11c34fb55",
    "state": "initialized",
    "created_at": "2017-11-07T13:00:54-05:00",
    "updated_at": "2017-11-07T13:00:54-05:00",
    "percent_done": 1,
    "activity_errors": [],
    "status": {},
    "_links": {
        "self": {
            "href": "/v3/activities/993d7bc0-c3e5-11e7-a1be-90b11c34fb55"
        }
    }
}

Check the Activity Status

Check on the status of a Delete Contacts activity using link to the activity status provided in the _links section of the response. The activity_id for your request is provided in the href link. To retrieve the status, make the following GET call:

GET https://api.cc.email/v3/activities/{activity_id}

Endpoint Requirements

User privileges: contacts:write

Authorization scopes: contact_data

Activity Status Response

{
    "activity_id": "fd430090-c331-11e7-a623-d4ae529a8612",
    "state": "completed",
    "started_at": "2017-11-06T15:35:30-05:00",
    "completed_at": "2017-11-06T15:35:30-05:00",
    "created_at": "2017-11-06T15:35:12-05:00",
    "updated_at": "2017-11-06T15:35:31-05:00",
    "source_file_name": "csv_from_json_2017-11-06T15_35_12-05_0020171106-25954-18q7wrs.csv",
    "percent_done": 100,
    "activity_errors": [],
    "status": {
        "items_total_count": 2,
        "person_count": 1,
        "error_count": 0,
        "correctable_count": 0,
        "cannot_add_to_list_count": 0
    },
    "_links": {
        "self": {
            "href": "/v3/activities/fd430090-c331-11e7-a623-d4ae529a8612"
        },
        "results": {
            "href": "/v3/file_imports/fd334920-c331-11e7-a623-d4ae529a8612"
    }
}

Try it!