Automate a Delete Contacts Process with REST API in Salesforce Marketing Cloud

Author: Florin Valean

Use case

Contact Delete is a very useful functionality and there can be a few scenarios when one would wish to remove contacts/subscribers from a Marketing Cloud account. For cost reasons we may want to keep the number of subscribers as low as possible at account level; from the GDPR perspective we want to be able to respond in a timely manner to any right to be forgotten request from customers.
The contact delete action can be initiated via an API call using the POST method to this URL:

/* replace YOUR_SUBDOMAIN with your subdomain generated when you create the Installed Package in Marketing Cloud */

In this exercise we are going to delete subscribers by Subscriber Key.


For this use case we are going to use an Installed Package created with enhanced functionality with a component of type API Integration and integration of type Server-to-Server. Make sure you assign all the scopes you need to the Installed Package.

OAuth 2.0 access token is required. For more details on how to obtain and how to use the access token go to this page.

The payload for /contacts/v1/contacts/actions/delete is in JSON format and it will look like this:

/* replace the highlighted values with your own Subscriber Keys that you want to be deleted */ { "ContactTypeId": 0, "values": ["12345, 123456789"], "DeleteOperationType": "ContactAndAttributes" }

Server-side javascript sample code

You can create a landing page in Web Studio and include this code. Publish the page and load it in a web browser to test the code.

/* replace the highlighted values with yours */ <script runat="server"> Platform.Load("Core", "1"); try { /* get OAuth 2.0 access token */ var payload = '{"grant_type": "client_credentials",'; payload += '"client_id": "d20aaul96htb2hgo9b4i47gx",'; payload += '"client_secret": "tUriuDS0zdV82vFrLIbJek77",'; payload += '"scope": null,'; payload += '"account_id": "012345678"}'; var OAuth2URL = ""; var contentType = 'application/json'; var accessTokenResult = HTTP.Post(OAuth2URL, contentType, payload); var tokenObj = Platform.Function.ParseJSON(accessTokenResult["Response"][0]); var accessToken = tokenObj.access_token; var headerNames = ["Authorization"]; var headerValues = ["Bearer " + accessToken]; /* create the payload */ var deletePayload = '{"ContactTypeId": 0,'; deletePayload += '"values": ["12345", "123456789"],'; deletePayload += '"DeleteOperationType": "ContactAndAttributes" }'; /* make the API call and get the response */ var content = [0]; var urlDelete = ""; var response = HTTP.Post(urlDelete, contentType, deletePayload, headerNames, headerValues, content); Write(Stringify(response)); } catch(e) { Write(Stringify(e)); } </script>

Notice the use of try-catch block - see this page for more details on how/when to use try-catch.

In this excercise we use the query string type=keys to specify that we want to delete contacts by keys. The other options are type=ids and type=listReference.
ContactTypeId specifies the type of contact to be deleted - it is based on where the contact originated. Type 0 (zero) is used for contacts/subscribers created in Marketing Cloud. All other contact types represent contacts created as a result of an integration:

If the API call was successful the response from the server would look like this:

{ "StatusCode": 200, "Response": [{ "operationInitiated": true, "operationID": 2, "requestServiceMessageID": "f2aee0d2-9804-4cf2-a1d4-aae87c8d9ee7", "responseDateTime": "2019-08-07T07:57:26.3591381-06:00", "hasErrors": false, "resultMessages": [], "serviceMessageID": "8351aa69-81d1-4ed9-bf6f-8f2e05b7d77a" }] }

Technical considerations

Be mindful that Contact Delete is a very complex task that runs in the background and it may take 24 hours or even more to complete. The recommendation is to always follow Salesforce's best practices - check out this page.

Automate a contact delete process

The server-side javascript presented in this article can be used in a script activity in Automation Studio and then it can be included in an automation and scheduled to run periodically. A common use case would be to store in a data extension all the Subscriber Keys that need to be deleted and then amend the script to dynamically create the values part of the payload by extracting the values from the data extension. Be considerate of the volume though :)

Share this page
Stay in touch

Subscribe to the newsletter

p1 p2 p3