Using the API for Data Subject Requests

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

📘

On premise Sombra configuration

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 an on premise 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.

Submit a DSR

To initiate a data subject request use this endpoint.

POST /v1/data-subject-request

Request headers

Header

Value

authorization

"Bearer API_KEY"
API_KEY must be configured with the Submit New Data Subject Request scope

Request body fields

Parameter

Type

Description

Example

subject -> coreIdentifier

String

The core identifier of the data subject

"id-123456789"

subject -> email

String

The email of the data subject

"[email protected]"

subjectType

String

Data subject class

"customer"

type

String

Type of data subject request, can be any one of these events

"ACCESS"

subject -> emailIsVerified (optional)

Boolean

When true, the data subject's email will be considered verified

true

subject -> attestedExtraIdentifiers (optional)

Object

Extra identifiers that have been attested to belong to the data subject

Note: these must correspond to defined identifiers that are connected to enrichers, detailed here.

{
"email": [{ "value": "[email protected]" }],
"custom": [{ "value": "mbrook", "name": "username" }]
}

isSilent (optional)

Boolean

When true, no emails will be sent to the data subject (including confirmation emails)

false

locale (optional)

String

Language preference, defaults to English ('en')

"en"

details (optional)

String

Miscellaneous details about the request

"Additional details about the request"

dataSiloIds (optional)

List

Specific data silos to process for the request

["f3f7af53-6c50-422c-afba-429fc58fd08f", "68d7021a-ce0d-4fd1-9cc4-29998236e02e"]

📘

Uploading DSRs without an email address

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.

Response body fields

Parameter

Type

Description

request

Object

Parent object

request -> id

String

Unique ID of the DSR (DSR_UUID in examples)

request -> status

String

Status of the DSR

request -> type

String

Type of data subject request, can be any one of these events, i.e. "ACCESS" or "ERASURE"

request -> subjectType

String

Data subject class

request -> email

String

Email provided in the data subject authorization context

request -> coreIdentifier

String

Core identifier provided in the data subject authorization context

Data subject request status

Value

Description

ARCHIVED

All data has been archived and only necessary records are kept around

APPROVING

The request is compiled and awaiting review before send

CANCELED

The request was canceled and the data subject was notified

COMPILING

The request begins compiling across the organization's datamap, specific to the actions requested

COMPLETED

The request has been approved and sent to the data subject with no secondary action

DELAYED

The 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

DOWNLOADABLE

The request is in a state where the data subject report zip can be downloaded

ENRICHING

The request identifiers have been verified and they are enriched to create other identifiers

FAILED_VERIFICATION

The data subject failed to verify at least one of the identifiers provided

ON_HOLD

The request is temporarily placed on hold

REQUEST_MADE

A data subject has submitted a DSR

REVOKED

The request was revoked because it was a duplicate (another open request covers it)

SECONDARY

The secondary request action begins compiling across the organization's datamap (i.e. ERASURE)

SECONDARY_COMPLETED

The secondary request action (i.e. ERASURE) completed compilation

Requests with the APPROVING, DOWNLOADABLE, or COMPLETED statuses have finished compiling data across your datamap 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.

Example DSR submission

var request = require('request');

var options = {
  method: 'POST',
  url: 'https://multi-tenant.sombra.transcend.io/v1/data-subject-request',
  headers: {
    'Authorization': 'Bearer API_KEY',
  },
  body: {
    subject: {
      coreIdentifier: "bfd219b5-19ce-4c32-a6cc-b8b0b2ba7fb7", 
      email: "[email protected]",
      emailIsVerified: true,
      attestedExtraIdentifiers: {
        email: [{ value: "[email protected]" }],
        phone: [{ value: "+13852904629" }],
        custom: [{ value: "mbrook", name: "username" }]
      }
    },
    subjectType: "customer",
    type: "ACCESS",
    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": "[email protected]"
      },
   "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": "[email protected]",
        "coreIdentifier": "bfd219b5-19ce-4c32-a6cc-b8b0b2ba7fb7"
    }
}

Poll DSR state

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>>

Request headers

Header

Value

authorization

"Bearer API_KEY"
API_KEY must be configured with the View Incoming Requests scope

Example DSR status poll

var request = require('request');

var options = {
  method: 'GET',
  url: 'https://multi-tenant.sombra.transcend.io/v1/data-subject-request/DSR_UUID',
  headers: {
    'Authorization': 'Bearer API_KEY',
  }
};

request(options, function (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"

Get the files to download

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

Request headers

Header

Value

authorization

"Bearer API_KEY"
API_KEY must be configured with the View the Request Compilation scope

Response body fields

Parameter

Type

Description

nodes

Array

List of files available for download

nodes-> [n] -> downloadKey

String

Access key for file, a long string

nodes -> [n] -> error

String

Nullable

nodes -> [n] -> mimetype

String

Media type

nodes -> [n] -> size

Integer

Size of the file in bytes

totalCount

Integer

Total number of files available for download

_links

Object

Pagination information

Example getting the files to download

var request = require('request');

var options = {
  method: 'GET',
  url: 'https://multi-tenant.sombra.transcend.io/v1/data-subject-request/DSR_UUID/download-keys',
  headers: {
    'Authorization': 'Bearer API_KEY',
  }
};

request(options, function (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"

Download individual files

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

GET /v1/files?downloadKey=<<downloadKey>>

Example file download

var request = require('request');

var options = {
  method: 'GET',
  url: 'https://multi-tenant.sombra.transcend.io/v1/files?downloadKey=DOWNLOAD_KEY',
};

request(options, function (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'