Perform GDPR Right to Erasure with Acoustic Exchange APIs

Prerequisites

Before you can remove records on behalf of a data subject, you must first have access to your account level authorization key. Your account level authorization key was provided to you in your provisioning email when you created your Acoustic Exchange account. If you cannot find your account level authorization key, contact Acoustic Exchange Support.

POST /v1/jobs/gdprRequest

About this API

You can remove all identifiers that are associate with a data subject and that data subject’s x1ID.

The input for this API is a CSV list of identifiers that are recognized by Acoustic Exchange. For example, email address, phone number, cookie ID, etc. The erasure operation is carried out on any x1IDs that are matched by those identifiers. Meaning that, if a controller specifies an email address in the call, then Acoustic Exchange scans through its database to find any x1IDs that have the email address associated with it. After the x1IDs are identified by Acoustic Exchange, deletes all the identifiers associated with an x1ID.

For example, if you pass an email address, and that email address is found in x1id “12345”, which also has cookie ID “A2234FE0014”, then the output will include the email address and the cookie ID, each associated with the x1ID. The additional identifiers that come in the output can be used to update other systems that may have the cookie ID but not the email address.

This API can have an operation type of “remove”, “addRestriction”, and “removeRestriction”. Each operation type removes, restricts, or removes the restriction on an x1ID and all of the identifiers that are associated with it.

API payload:

{
 "operationType" : "remove" | "addRestriction" | "removeRestriction",
 "generateOutput" : true | false
}

For the purpose of removing data associated with an x1ID, you must designate the operation type as “remove”. Optionally, you can set “generateOutput” to “true”. “generateOutput” is set to “false” by default.

Example call:

POST <base URL>/v1/jobs/gdprRequest
Authorization: Bearer {account level auth key}
{
 "operationType" : "remove"
 "generateOutput" : "true"
} 
After the call is made, it creates a job to initiate the removal process the returns the job ID for that job in the response playload.

Example response payload:

{
 "jobId" : "2345"
}

GET /v1/jobs/GDPR_REQUEST/{jobId}

Next, check on the status of the job to determine if the initial call was successful. If the call was successful, then the job’s status shows as “WAITING_TO_RECEIVE_DATA”. If the call was unsuccessful, then the job status shows as “ERROR”.

Example response payload:

{
 ...
 "status" : "WAITING_TO_RECEIVE_DATA"
 ...
}

POST /v1/jobs/{jobId}/data

Indicate a series of identifiers as a comma separated value (CSV) that are associated with a particular data subject. Acoustic Exchange will use these identifiers to find if there are any x1Ids are associated with those identifiers.

Example call:

POST <base URL>/v1/jobs/2345/data
Authorization: Bearer {account level auth key}
{
Type,Value
email, [email protected]

email, [email protected]
...
cookieId, recipient3cookieId
...
x1Id, 123-abc-456-def
...
}

GET /v1/jobs/GDPR_REQUEST/{jobId}

In this step of the process, you check to see the status of the job. If you call this API and the status is “RUNNING”, that means that Acoustic Exchange is still matching identifiers to x1IDs. Give it a little more time and try the call again. When the job has finished running, then the status changes to “READY_FOR_DOWNLOAD”, and returns the names of the gdprDataFiles. Each gdprDataFile represents data that is associated with a particular data subject and its corresponding x1IDs.

Note: If an x1ID is too large to be contained in one gdprDataFile, then it is split across multiple gdprDataFiles.

If the call returns a “COMPLETE” status and you did not set “generateOutput”: true, then the process is complete and the content is deleted.

If this call returns a “COMPLETE” status and you did set “generateOutput”: true, then none of the provided identifiers were associated with any x1IDs in Acoustic Exchange.

Example response payload:

{
 "jobCategory": "GDPR_REQUEST",
 "jobId": 2345,
 "status" : "READY_FOR_DOWNLOAD",
 "jobName": "remove",
 "accountId": 2,
 "subStatus": null,
 "errorDetails": null,
 "generateOutput": true,
 "gdprDataFiles" : [ 
 "2|gdpr|2345_1.segment.output", 
 "2|gdpr|2345_2.segment.output"
 ],
 "inputRecordCount": 4
 "updatedOrRemovedIdentityCount": 2,
 "outoutRecordCount": 2,
 "skippedInputRecordCount": 1,
}

GET /v1/jobs/gdprDataFiles/{jobId}/{gdprSegmentOutput}

In this call, you indicate the gdprDataFiles that were returned in the GET /v1/jobs/gdprRequest/{jobId} call. If there were multiple data files returned in the previous call, then you will need to call this API once for each data file. After the call is successfully made, it returns the content of the data file in comma separated value (CSV) format.

You can use the this information to determine how many identifiers are associated with a particular data subject.

Example CSV data output:

X1Id, Type, Endpoint ID, Name, Value
32bd12345-kjei-4654-wepm,EMAIL,45,61,email_src,[email protected]

DELETE /v1/jobs/gdprDataFile/{jobId}/{gdprSegmentOutput}

To delete identifiers that are associated with an X1Id, and by extension a data subject, indicate the gdprDataFiles that were returned in the GET /v1/jobs/gdprRequest/{jobId} call. As before, if there were multiple data files returned in the previous call, then you will need to call this API once for each data file.

Example

DELETE <base URL>/v1/jobs/gdprDataFile/2345/2|gdpr|2345_1.segment.output

PUT /v1/jobs/{jobId}/status/complete

This final step in this process is to mark the job as complete. This insures that no inactive jobs are left running in the system.

Example call:

PUT <base URL>/v1/jobs/2345/status/complete