Overview

Rokt’s Data Deletion APIs allow our clients to send and manage data subject deletion requests to our platform. These APIs automate processes relating to customer data and privacy regulation, and execute them with more confidence and less risk.

Rokt supports data deletion requests for specific accounts that have been whitelisted by Rokt. If your account hasn’t been whitelisted and requires access to data deletion, please contact your Rokt account manager.

Functionality

Data deletion requests are currently queued for 15 days before being actioned upon by Rokt internal systems. The lifecycle of a request is described as follows:

Deletion requests are:

• Created via API call in a PENDING state.
• Moved to the READY state after 12 days (~288hrs ).
  • Once in the READY state our internal OPS team is alerted for additional manual review if needed.
• Passed through to our internal systems after 3 days (~72hrs) and actioned within a max of 15 additional days - taking the overall maximum process length to 30 days.
• Only able to be cancelled when in the PENDING or READY state via API calls. The status will change to CANCELLED and it can be retrieved in any subsequent GET tasks calls.

Authentication

The Rokt Data Deletion APIs share the same authentication mechanism implemented for the Event and Reporting APIs as described in our authentication instructions.

In order to access the APIs you need an AppId and the related AppSecret. These can be generated on the Rokt dashboard as described in the documentation above. Alternatively, you can contact your account manager to help guide you through the process.

API Structure

The base URL for the data deletion APIs is: https://api.rokt.com

The following endpoints are currently available:

Method	Endpoint	Purpose
POST	/data/deletion-requests/emails	Creates a new user data deletion request. Users are identified currently by raw email address (list of), hashed (SHA256) email address (list of).
GET	/data/deletion-requests	Returns a list of current (PENDING, READY) and past (ACTIONED, CANCELLED) data deletion requests to verify their status.
DELETE	/data/deletion-requests/:task_id	Allows an API user to cancel a data deletion request that is in the READY and PENDING states only.

Endpoints

Create request

Endpoint	/data/deletion-requests/emails
Method	POST
Query Params	none

Example request:

{
  "accountId": "2456192011195196284677",
  "rawEmails": [
    "test@test.com"
  ],
  "sha256Emails": [
    "kJbnntuJYvQBhPiiHQcz6OSn0EyvzVeOBmtsG2sWkyU="
  ]
}

Example response: Http Code 202

Notes:

• Each deletion request can contain multiple entries in each of the 3 lists: rawEmails, and sha256Emails.
• At least 1 entry across the 3 lists need to be populated for the request to be valid.
• sha256Emails need to be provided in base64 encoding.

GET deletion requests

Endpoint	/data/deletion-requests
Method	GET
Query Params	none
Example Request	none

Example response

[
    {
        "taskId": "20675afe-f4e5-4ee6-bfb7-d5fddcffe16d",
        "status": "actioned",
        "deletionType": "emailsDeletion",
        "creationTime": "2022-03-01T11:00:00+11:00",
        "accountId": "3008848650853038987",
        "readyTime": null,
        "actionedTime": null,
        "cancelledTime": null
    }
]

Cancel deletion request

Endpoint	/data/deletion-requests/:taskId
Method	DELETE
Query Params	In the URI - taskId: the id of the deletion request that will be cancelled
Example Request	none

Example response

{
  "data": {
    "message": "successful cancelled task with taskId: 3bc2e8b0-88ee-400c-8696-44897bc95cd3"
  }
}  

Error handling

All APIs follow the most common RESTful error response codes: 400, 403, 404, 500, etc.

Any error is reported to the caller in the following JSON format:

{
  "error": {
    "code": 404,
    "error": "NOT_FOUND",
    "message": "task not found for with task_id:..."
  }
}

The following error codes are currently supported:

HTTP Code	Error	Explanation
400	BAD_REQUEST	The request is malformed or incomplete
500	INTERNAL_SERVER_ERROR	Internal server error
403	AUTHENTICATION_ERROR	Unable to authenticate the request
403	UNAUTHORIZED_ACCOUNT	The account used is currently not authorised for data deletion requests
404	NOT_FOUND	Resource not found
410	DEADLINE_EXCEEDED	The deletion request cannot be cancelled as it’s past its PENDING and READY states