Consumer Data Privacy API

This document assumes that the reader has already created an API user and is capable of obtaining a token via the Monetate /refresh endpoint. If you're unfamiliar with these steps, refer to Manage API Keys.

New privacy policies and regulations require companies to delete customer data upon request. To help comply with these regulations, Monetate provides an API endpoint that accepts a list of customer IDs that should be deleted from its database. After deleting a customer ID, Monetate continues to purge that ID from its system if it is recognized in any future sessions.

Creating the customer_data_privacy Dataset

To start, you must create a new dataset using a schema type called customer_data_privacy. This is a one-time configuration that defines a two-column dataset of customer_id and delete_request_time.

Use the Create Endpoint endpoint. Fields do not have to be defined because the schema type does this by default.

Create Endpoint

Submit a support ticket using the Monetate Technical Support portal (support.monetate.com) to obtain your account's shortname if you do not already know it.

/api/data/v1/<shortname>/production/schema/

Example Request Header

Authorization: Token <token>
Content-Type: application/json

Example Request Body

{
  "type": "customer_data_privacy",
  "name": "<unique_dataset_name>",
  "fields": {}
}

The schema creation process allows you to supply extra columns beyond the two required attributes. However, these fields are not used in any capacity.

Posting Data to the customer_data_privacy Dataset

Once you create a customer_data_privacy dataset, you can begin sending customer IDs to Monetate through the dataset. Doing so triggers a process to delete those IDs from Monetate's database. You must provide two attributes in the request:

  1. customer_id — The unique identifier for the customer to be removed
  2. delete_request_time — The timestamp for when the customer's removal request was received. This timestamp should be in the ISO 8601 standard format (YYYY-MM-DD).

Send Data Endpoint

/api/data/v1/<shortname>/production/data/<insert_unique_dataset_name>/

Example Request Header

Authorization: Token <token>
Content-Type: application/json

Example Request Body

{
  "customer_id": "ABC123",
  "delete_request_time": "2019-05-23T12:01:00.000000Z"
}

If you created the dataset with extra columns, they can be passed with the rest of the data, but this data is ignored.

If you've already created a dataset created but don't know the unique dataset name, then select API Documentation from the settings in the Monetate platform. Refer to the Monetate Data API section within that documentation.

Verify customer_id Deletion Status

Monetate processes deletion requests through a series of nightly batch jobs. Requests typically take 24 to 48 hours to complete. After completion, the customer IDs no longer are in Monetate's system. To confirm that a customer ID has been deleted, you can query the following endpoint.

Customer ID Status Endpoint

/api/data/v1/<shortname>/production/customer-data-privacy/<insert_unique_dataset_name>/?id=<customer_id>

The required customer_id is the customer ID for which you're submitting the status query.

Required Headers

Authorization: Token <api_token>

This can be the same token as used in the endpoints above. Any valid API token works if you want to use different API users for different systems.

Example Response Body

{
  "meta": {
    "code": 200
  },
  "data": {
    "status": <string : oneOf(PENDING, FOUND, NOT_FOUND)>,
    "description": <string>
  }
}

Statuses

  • PENDING — The customer_id has been found within Monetate's data stores and is pending removal.
  • FOUND — The customer_id has been found within Monetate's data stores.
  • NOT_FOUND — The customer_idhas not been found within Monetate's data stores.

    This status is expected once the customer_id has been completely removed from Monetate's data stores.

Possible Error Response Codes

  • 401 UNAUTHORIZED
  • 403 FORBIDDEN
  • 404 NOT FOUND
  • 500 SERVER ERROR

Submit a support ticket using the Monetate Technical Support portal (support.monetate.com) if you do not receive a NOT_FOUND status 48 hours after submitting your request.