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][contacts_delete].
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][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"
}
}