Perform GDPR Right of Access with Acoustic Exchange APIs

Prerequisites

Before you can restrict 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 Exchange account. If you cannot find your account level authorization key, contact Support.

POST /v1/jobs/gdprRequest

About this API

You can restrict 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, which you provide, that are recognized by Exchange. For example, email address, phone number, cookie ID, etc. The restriction 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 Exchange scans through its database to find any x1IDs are that have the email address associated with it. After the x1IDs are identified by Exchange, restricts all the identifiers associated with an x1ID for future processing.

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
}

The “addRestriction” operation sets a “restricted” flag on the x1ID. If the flag is set, subsequent audience and event shares which match the x1ID are dropped, and the x1ID is not joined or augmented.

A “removeRestriction” operation removes the “restricted” flag from the x1ID.

For the purpose of restricting data associated with an x1ID, you must designate the operation type as “addRestriction”. 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" : "addRestriction"
"generateOutput" : "true"
}

After the call is made, it creates a job to initiate the restriction process 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

In this call, you indicate a series of identifiers as a comma separated value (CSV) that are associated with a particular data subject. Exchange will use these identifiers to find if there are any x1Ids are associated with those identifiers.

Example call:

POST <base URL>/v1/jobs/<jobId>/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 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 status changes to “READY_FOR_DOWNLOAD”, then the identifiers and x1ID that are associated with a data subject are restricted and will no longer be processed by UBX.

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": "addRestriction",
 "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,
}

Optional: 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]