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"
}
}