Information for: DEVELOPERS   PARTNERS   SUPPORT

Looking for something?

Using the data erasure API

You can leverage the data erasure API to make data erasure requests in bulk on your customer’s behalf. Note that you can make the data erasure request for a maximum of 200 records in a single batch. However, if you have limited records, Acquia recommends you to leverage the data erasure feature in the CDP user interface. For more information, see Data Erasure Requests.

Prerequisites

Before you implement the API, review the data that you want to send to CDP, and compare it to what other systems send to CDP. All data sources can send data about any entity to CDP, without any notion of priority. For more information, see Customer Data Platform (CDP) entities. Therefore, the data sent in your API overwrites the previous data for the related entity if that entity existed prior to your API call. Also, the data sent in your API can later be overwritten by any other system in the same way.

To re-iterate, the platform is flexible in what data can be accepted. Therefore, you must send data from sources that you trust, and ensure that you do not send overlapping data from other sources.

To make API calls to the CDP platform, you must obtain the bearer token through the authentication API. For more information, see Requesting a new token for data erasure.

Endpoint and payloads

Base API endpoint

https://<environmentSubdomain>.agilone.com/v2/{tenantId}/dw/dataerasure

For example,

https://api6.agilone.com/v2/1234/dw/dataerasure

In the preceding API endpoint, subdomains differ per environment:

Environment Pre-Production Production
US AWS cs-api6 api6
EU AWS cs-api6.eu api6.eu
US GCP cs-gcp-api6 api8

API query parameter

You can use the following optional query parameter with the API:

  • failOnNotFound: Set this parameter to true to fail the API request if the customer Id is not found. The default value is false. With this parameter, the API endpint becomes:

    https://<environmentSubdomain>.agilone.com/v2/{tenantId}/dw/dataerasure?failOnNotFound=<true or false>

Method

POST

Request parameters

To send data to CDP through the data erasure request API, you must set the HTTPS header: content-type to application/json.

You can send the following request parameters in the payload:

Parameter Required? Data Type Description
reason Yes String

The reason for making the data erasure request. This is a free text field and you can specify a value based on the following:

  • GDPR: Erasure request is made by the data subject.
  • GDPR: Data is no longer relevant to the business.
  • CCPA: Erasure request is made by the consumer.
  • Other: Any reason other than the ones listed earlier.
customerIds Yes String The list of known customer IDs. If you do not include all the customer IDs associated with the customer, data is partially erased. For information on all the customer IDs associated with a customer, see New dashboard experience.
requestOrigin Yes String The consumer app, such as API that initiates the request. This parameter does not have a default value. However, ensure that you specify a well-defined value to accurately indicate the source system.
requestedDate Yes String The date when the request was made. This can be derived from the application server time. This date can be a current or past date but not a future date. The format of this value is yyyy-MM-dd HH:mm:ss z and a sample value is 2022-02-03 00:00:00 UTC.
requestedBy No String The user who requested the data erasure.

Sample request body

{
  "reason": "<DataErasureReason>",
  "customerIds": [
    "<customerId1>",
    "<customerId2>",
    "<customerIdN>"
  ],
  "requestOrigin": "<requestOrigin>",
  "requestedDate": "yyyy-MM-dd HH:mm:ss z",
  “requestedBy” : “<FreeText-ActualRequester>”
}

Response parameters

If the API call is successful, CDP sends the values for the following parameters in the response:

Parameter Description
eventId The unique ID that tracks the data erasure status for the group of customers ready for erasure in a single request.
readyForDataErasure The list of customer IDs found and added to the data erasure queue.
notFound The list of customer IDs not found and not added to the data erasure queue.
pendingForDataErasure The list of customer IDs ignored because of a pending data erasure request.
failedToAccept The list of customer IDs failed to register for some internal errors.

Note

To view the status of your data erasure request in the CDP user interface, sign in to the CDP user interface and click Data Erasure. For more information, see Data Erasure Requests

Success response code

200

Sample success response body

{
  "eventId": "<eventId>",
  "readyForDataErasure": [
    "<customerId1>",
    "<customerId2>",
    "<customerIdN>"
  ],
  "notFound": [
    "<customerId1>",
    "<customerId2>",
    "<customerIdN>"
  ],
  "pendingForDataErasure": [
    "<customerId1>",
    "<customerId2>",
    "<customerIdN>"
  ],
  "failedToAccept": [
    "<customerId1>",
    "<customerId2>",
    "<customerIdN>"
  ]
}

Sample failure response codes

  • 400: There is an invalid or bad request. When checking if the request payload contains all the necessary information and If the request misses any of the required fields or has invalid values, the system outputs this code. For example, you get this error if you make the data erasure request for more than 200 customer IDs through a single API call.
  • 404: There is no valid customer ID found in the data warehouse.
  • 500: There is intermittent API or server error.

Sample success response body:

{
    "errorCode": <errorCode>,
    "userMessage": <errorMessage>,
    "developerMessage": <errorDetails>
}

53 State Street, 10th Floor
Boston, MA 02109
United States
Phone: 888-922-7842