These endpoints enable Transcend customers to complete an end-to-end data subject (DSR) request (such as ACCESS or ERASURE) on behalf of their users.

These endpoints can be used in combination with or in lieu of Configuring the Privacy Center.

This flow can be achieved end-to-end via four endpoints:

  1. Submit a DSR
  2. Poll DSR state
  3. Get the files to download
  4. Download individual files

All of the examples below demonstrate how to access Transcend with our default encryption configuration: multi-tenant Sombra.

In order to use these endpoints with a self-hosted Sombra instance, add the x-sombra-authorization header to requests and change the base URL from https://multi-tenant.sombra.transcend.io to your gateway's URL.


To initiate a data subject request use this endpoint.

POST /v1/data-subject-request

HeaderValue

ParameterTypeDescriptionExample
subject -> coreIdentifierStringThe core identifier of the data subject"id-123456789"
subject -> emailStringThe email of the data subject"user@example.com"
subjectTypeStringData subject class"customer"
typeStringType of data subject request, can be any one of these events"ACCESS"
subject -> emailIsVerified (optional)BooleanWhen true, the data subject's email will be considered verifiedtrue
subject -> attestedExtraIdentifiers (optional)ObjectExtra identifiers that have been attested to belong to the data subjectObject
isSilent (optional)BooleanWhen true, no emails will be sent to the data subject (including confirmation emails)false
locale (optional)StringLanguage preference, defaults to English ('en')"en"
details (optional)StringMiscellaneous details about the request"Additional details about the request"

When isSilent is set to true, the subject -> email field can be omitted. When this field is set to false, an email address is required in order to send the data subject updates about their DSR.


ParameterTypeDescription
requestObjectParent object
request -> idStringUnique ID of the DSR (DSR_UUID in examples)
request -> statusStringStatus of the DSR
request -> typeStringType of data subject request, can be any one of these events, i.e. "ACCESS" or "ERASURE"
request -> subjectTypeStringData subject class
request -> emailStringEmail provided in the data subject authorization context

ValueDescription
ARCHIVEDAll data has been archived and only necessary records are kept around
APPROVINGThe request is compiled and awaiting review before send
CANCELEDThe request was canceled and the data subject was notified
COMPILINGThe request begins compiling across the organization's data silos, specific to the actions requested
COMPLETEDThe request has been approved and sent to the data subject with no secondary action
DELAYEDThe primary action (i.e. ACCESS) has been sent to the data subject and the request is delayed until the secondary action (i.e. ERASURE) is executed
DOWNLOADABLEThe request is in a state where the data subject report zip can be downloaded
ENRICHINGThe request identifiers have been verified and they are enriched to create other identifiers
FAILED_VERIFICATIONThe data subject failed to verify at least one of the identifiers provided
ON_HOLDThe request is temporarily placed on hold
REQUEST_MADEA data subject has submitted a DSR
REVOKEDThe request was revoked because it was a duplicate (another open request covers it)
SECONDARYThe secondary request action begins compiling across the organization's data silos (i.e. ERASURE)

Requests with the APPROVING, DOWNLOADABLE, or COMPLETED statuses have finished compiling data across your data silos and have files available for download and review, if there are any. Requests can be marked as completed once in the COMPLETED state, or for requests that require a secondary action (e.g. erasure requests), once in the SECONDARY_COMPLETED state.


var request = require('request');
var options = {
method: 'POST',
baseUrl: 'https://multi-tenant.sombra.transcend.io',
uri: '/v1/data-subject-request',
headers: {
Authorization: 'Bearer API_KEY',
},
body: {
subject: {
coreIdentifier: 'bfd219b5-19ce-4c32-a6cc-b8b0b2ba7fb7',
email: 'jane@transcend.io',
emailIsVerified: true,
attestedExtraIdentifiers: {
email: [{ value: 'another-email@example.com' }],
phone: [{ value: '+13852904629' }],
custom: [{ value: 'mbrook', name: 'username' }],
},
},
subjectType: 'customer',
type: 'ACCESS',
// emailReceiptTemplateId: '9a558f86-51d4-4237-8c2d-494551991989',
isSilent: true,
},
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
curl --location --request POST \
'https://multi-tenant.sombra.transcend.io/v1/data-subject-request'
-H "Content-Type: application/json" \
-H "authorization: Bearer API_KEY" \
--data-raw '{
"subject": {
"coreIdentifier": "Jane Smith",
"email": "jane@transcend.io"
},
"subjectType": "customer",
"type": "ACCESS"
}
'

You should get a response back that looks like:

{
"request": {
"id": "e6de987f-bdc7-44a3-9101-cf7355197fd6",
"status": "COMPILING",
"type": "ACCESS",
"subjectType": "customer",
"email": "jane@transcend.io",
"coreIdentifier": "bfd219b5-19ce-4c32-a6cc-b8b0b2ba7fb7"
}
}

Once a DSR has been submitted, it will take some time to complete. The status of the DSR can be accessed via the following endpoint.

GET /v1/data-subject-request/{{id}}

HeaderValue

const request = require('request');
const options = {
method: 'GET',
baseUrl: 'https://multi-tenant.sombra.transcend.io',
uri: '/v1/data-subject-request/{DSR_UUID}',
headers: {
Authorization: 'Bearer {API_KEY}',
},
};
request(options, (error, response) => {
if (error) throw new Error(error);
console.log(response.body);
});
curl --location --request GET \
'https://multi-tenant.sombra.transcend.io/v1/data-subject-request/{DSR_UUID}'
-H "authorization: Bearer API_KEY"

Once the status of the original DSR indicates there are files available to download, it is possible to get a list of these files for download.

GET /v1/data-subject-request/{{id}}/download-keys?limit=25&offset=0

HeaderValue

ParameterTypeDescription
nodesArrayList of files available for download
nodes-> [n] -> downloadKeyStringAccess key for file, a long string
nodes -> [n] -> errorStringNullable
nodes -> [n] -> mimetypeStringMedia type
nodes -> [n] -> sizeIntegerSize of the file in bytes
totalCountIntegerTotal number of files available for download

const request = require('request');
const options = {
method: 'GET',
baseUrl: 'https://multi-tenant.sombra.transcend.io',
uri: '/v1/data-subject-request/DSR_UUID/download-keys',
headers: {
Authorization: 'Bearer API_KEY',
},
};
request(options, (error, response) => {
if (error) throw new Error(error);
console.log(response.body);
});
curl --location --request GET \
'https://multi-tenant.sombra.transcend.io/v1/data-subject-request/DSR_UUID/download-keys'
-H "authorization: Bearer API_KEY"

With the downloadKey in hand, it is possible to download the files generated by the DSR.

GET /v1/files?downloadKey={{downloadKey}}

const request = require('request');
const options = {
method: 'GET',
baseUrl: 'https://multi-tenant.sombra.transcend.io',
uri: '/v1/files?downloadKey={DOWNLOAD_KEY}',
};
request(options, (error, response) => {
if (error) throw new Error(error);
console.log(response.body);
});
curl --location --request GET \
'https://multi-tenant.sombra.transcend.io/v1/files?downloadKey=DOWNLOAD_KEY'