Delete Contacts with the REST API

Learning Objectives

After completing this unit, you’ll be able to:

Delete contacts in batches using REST API.
Get the status for Contact Delete requests.
Troubleshoot contact deletion requests.

Delete Contacts More Efficiently

Deleting one or two contacts directly from Marketing Cloud Engagement is simple enough, but if you’re deleting more than a handful, the process can quickly become tedious. So, while the limit per request batch is one million contacts, we don’t expect you to select that number of contacts manually. So, if you do need to delete a large number of contacts (and you’ve done your homework to make sure deleting contacts is the best choice), you have several REST API resources available to do this in Marketing Cloud Engagement.

Enable Contact Delete

Remember, Contact Delete needs to be enabled before you begin—refer to the previous unit for a refresher on how to do that. Similarly, you can modify the suppression period for your account with the configSettings resource, as shown in this example.

Example: Configure the Contact Delete Suppression Period

This example sets the value to 0 days (using a value of -1), or an immediate deletion.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete/configSettings
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "items" : [{
      "settingKey" : "SuppressionRestoreUntilDays",
      "value" : "-1"
      }
   ]

Choose How to Delete Contacts with REST API

Now that your account is enabled to delete contacts, you can use one of three different values to choose which contacts to delete: contact IDs, contact keys, or data extensions. Let’s take a closer look at each, along with some sample code.

Contact IDs

If you choose to delete contacts using a contact ID value, you should pass the values in an array, as shown in this example.

Example: Delete Contacts by Contact ID

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=ids
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "values": [12345678, 12345679],
    "DeleteOperationType": "ContactAndAttributes"
}

Contact Keys

If you choose to delete contacts using the ContactKey value, you should also pass these values in an array.

Example: Delete Contacts by Contact Key

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=keys
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "values": [
      "TEST_317-531-5555", "TEST_317-531-5556"
      ],
   "DeleteOperationType": "ContactAndAttributes"
}

Data Extensions

You can also choose to remove all contacts contained in a specific data extension. Remember that this operation deletes the contact records outlined in the data extension across all sendable data extensions. That includes data extensions that send based on ContactKey, ContactID, and Email Address values. You can also decide whether or not to delete the entire data extension when you’re done. So many choices!

This process creates an asynchronous request for your batch of delete requests. You can contact your Marketing Cloud Engagement account manager for more information on configuring delete request limits in your account.

You must specify that you’re deleting a data extension and include the external key for that data extension. Also, you can’t delete synchronized data extensions. You can use them to help identify the contacts to delete, but the actual data extension remains.

Example: Delete Contacts Using a Data Extension

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
POST /contacts/v1/contacts/actions/delete?type=listReference
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{
   "deleteOperationType": "ContactAndAttributes",
   "targetList": {
      "listType": {
         "listTypeID": 3
      },
   "listKey": "ContactListDeleteSource_as_DataExtension"
   },
   "deleteListWhenCompleted": false,
   "deleteListContentsWhenCompleted": false
}

Check Up on Your Requests

As we’ve mentioned, Contact Delete requests take some time to complete. It can take several hours, in fact, depending on how many contacts you included in your request, how many requests you made, and other system factors. However, you can keep up to date on the progress for your requests by using the OperationID value. Each Contact Delete request returns an OperationID value, which you can use to retrieve any available information. Here are a few example requests.

Example: Get the Status for a Specific Contact Delete Request

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET /contacts/v1/contacts/actions/delete/status?operationID=IDVALUEHERE
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

This example response shows the information for a deleted contact.

{
   "operation": {
      "listTypeID": 3,
      "listIdentifier": "037c2811-ce62-4381-b3d2-1936e51fbf4d",
      "listKey": "037c2811-ce62-4381-b3d2-1936e51fbf4d",
      "expectedListCount": 1,
      "deleteType": "ContactAndAttributes",
      "deleteListOnCompleted": false,
      "operationID": 2,
      "eID": 12345,
      "mID": 12345,
      "employeeID": 30980,
      "operationRequestID": "21d0d10d-a15a-413c-bc3e-8b43b185e551",
      "status": "Completed",
      "scheduledTime": "2016-06-14T16:01:58.107",
      "retryCount": 0,
      "createdDate": "2016-06-14T16:02:00",
      "createdBy": 30980,
      "modifiedDate": "2016-06-14T16:02:00",
      "modifiedBy": 30980
    },
    "requestServiceMessageID": "93631be1-107f-4239-a8b7-cdae245d7403",
    "resultMessages": [],
    "serviceMessageID": "00e6add8-d79a-4bd6-9568-2f2a272538f0"
}

Example: Retrieve Contact Delete Requests by Date

You can also retrieve a summary of requests made during a specified date range.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET contacts/v1/contacts/analytics/deleterequests?startdateutc=2019-02-18T00%3A00%3A00&amp;enddateutc=2019-03-19T00%3A00%3A00&amp;%24page=1&amp;%24pagesize=20&amp;%24orderby=operationId%20desc&amp;statusid=5
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
{

The response includes the OperationID values and brief summaries for all applicable requests. For more specific information, use the OperationID with the /contacts/v1/contacts/actions/delete/status?operationID= resource.

"startDateUtc":"2019-02-18T00:00:00",
"endDateUtc":"2019-03-19T00:00:00",
"statusAsOfDateUtc":"2019-03-19T19:33:17.496471Z",
"pageNumber":1,
"pageSize":20,
"operations":[
   {
      "operationId":22944,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-03-04T22:42:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-19T04:47:40.293",
      "deleteMethod":"Contact Key/ID"
   },
   {
      "operationId":22943,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-03-04T22:41:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-19T04:47:40.293",
      "deleteMethod":"Contact Key/ID"
   },
   {
      "operationId":22625,
      "totalContactCount":1,
      "completedContactCount":1,
      "receivedDateUtc":"2019-02-26T23:26:00",
      "status":"Completed",
      "lastStatusDateUtc":"2019-03-13T10:10:17.9",
      "deleteMethod":"Contact Key/ID"
   }
   ],
   "requestServiceMessageID":"e1198208-6432-40fd-b5ae-172c9d9bc44a",
   "responseDateTime":"2019-03-19T13:33:18.2141124-06:00",
   "resultMessages":[],
   "serviceMessageID":"ef7d833c-509f-4dbc-8f99-060aac3c0382"
}

Example: Retrieve a Summary of Contact Delete Requests

This example shows a summary of status reports for all requests during the specified time period.

Host: https://YOUR_SUBDOMAIN.rest.marketingcloudapis.com
GET contacts/v1/contacts/analytics/deleterequests/summary?startdateutc=2018-01-15T00:00:00Z&enddateutc=2018-01-15T05:00:00Z
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

The example response breaks the requests into completed, processing, or invalid.

{
   "startdateutc":"2018-01-15T00:00:00Z",
   "enddateutc":"2018-01-15T04:30:00Z",
   "statusofdateutc": "2018-01-17T04:30:00Z",
   "interval":"0",
   "itemcount":5,
   "totaltimeseries":[
      {
         "requestcount":500,
         "minvalue":100,
         "maxvalue":100,
         "items":[
            {time:"01-15-2018 00:00:00","value":100},
            {time:"01-15-2018 01:00:00","value":100},
            {time:"01-15-2018 02:00:00","value":100},
            {time:"01-15-2018 03:0000:","value":100},
            {time:"01-15-2018 04:00:00","value":100}
         ]
      }],
      "statustimeseries":[
         {
            "statusid": 5,
            "status": "Completed",
            "requestcount":350,
            "minvalue":0,
            "maxvalue":100,
            "items":[
               {time:"01-15-2018 00:00:00","value":100},
               {time:"01-15-2018 01:00:00","value":100},
               {time:"01-15-2018 02:00:00","value":100},
               {time:"01-15-2018 03:00:00","value":50},
               {time:"01-15-2018 04:00:00","value":0}
            ]
         },
         {
            "statusid": 1,
            "status": “Processing”,
            "requestcount":100,
            "minvalue":0,
            "maxvalue":75,
            "items":[
               {time:"01-15-2018 00:00:00","value":0},
               {time:"01-15-2018 01:00:00","value":0},
               {time:"01-15-2018 02:00:00","value":0},
               {time:"01-15-2018 03:00:00","value":25},
               {time:"01-15-2018 04:00:00","value":75}
            ]
         },
         {
            "statusid": 7,
            "Status": "Invalid",
            "requestcount":50,
            "minvalue":0,
            "maxvalue":50,
            "items":[
               {time:"01-15-2018 00:00:00","value":0},
               {time:"01-15-2018 01:00:00","value":0},
               {time:"01-15-2018 02:00:00","value":0},
               {time:"01-15-2018 03:00:00","value":25},
               {time:"01-15-2018 04:00:00","value":25}
            ]
         }]
}

You can use OperationID values to follow up on invalid or processing requests.

That was a lot of code, right? Let’s take a break from the code and head to the final unit to learn the best way to avoid pitfalls when deleting contacts.