To initiate a data subject request use this endpoint.

POST

/v1/data-subject-request

Request Authorization

In your request headers, pass authorization: Bearer <<token>>.

If you're self-hosting Sombra, also add the request header x-sombra-authorization: Bearer <<sombraInternalKey>>. You can read more about request authorization here.

Requires scope:

Submit New Data Subject Request

Request Parameters

Header Parameters

authorization string
An API key generated from the Transcend dashboard: https://app.transcend.io/infrastructure/api-keys.
x-sombra-authorization string
The Sombra internal key. This header is only needed for self-hosted Sombra gateways. See https://docs.transcend.io/docs/dsr-automation/api-integration/authentication#authenticating-to-sombra
content-type string
Specifying content-type: application/json for a JSON response from the Transcend API.

Request Body

application/json

type string(required)enum: "ACCESS" | "ERASURE" | "RECTIFICATION" | "RESTRICTION" | "BUSINESS_PURPOSE" | "PLACE_ON_LEGAL_HOLD" | "REMOVE_FROM_LEGAL_HOLD" | "AUTOMATED_DECISION_MAKING_OPT_OUT" | "USE_OF_SENSITIVE_INFORMATION_OPT_OUT" | "CONTACT_OPT_OUT" | "SALE_OPT_OUT" | "TRACKING_OPT_OUT" | "CUSTOM_OPT_OUT" | "AUTOMATED_DECISION_MAKING_OPT_IN" | "USE_OF_SENSITIVE_INFORMATION_OPT_IN" | "SALE_OPT_IN" | "TRACKING_OPT_IN" | "CONTACT_OPT_IN" | "CUSTOM_OPT_IN"
Type of data subject request, can be any one of these events (https://docs.transcend.io/docs/receiving-webhooks#events).
subject object(required)
attributes array<object>
Key-value pairs used to label data subjects
subjectType string(required)
The class of data subject, e.g. "customer", "subscriber".
region object
Specify the region that the request is submitting from. See https://github.com/transcend-io/privacy-types/blob/main/src/isoConstants/iso3166-1.ts
isSilent boolean
When true, no emails will be sent to the data subject (including confirmation emails).
isTest boolean
When true, the request will be flagged as a test request. (useful for auditing purposes). Test requests still operate on your live integrations.
locale stringenum: "en" | "ar" | "fr" | "es" | "de" | "it" | "ja" | "ru" | "ar-AE" | "fr-FR" | "de-DE" | "de-AT" | "de-CH" | "it-IT" | "it-CH" | "af-ZA" | "bg-BG" | "zh-CN" | "hr-HR" | "cs-CZ" | "da-DK" | "en-GB" | "en-CA" | "en-AE" | "fi-FI" | "el-GR" | "hi-IN" | "hu-HU" | "id-ID" | "ja-JP" | "ko-KR" | "lt-LT" | "ms-MY" | "mr-IN" | "nb-NO" | "pl-PL" | "pt-BR" | "pt-PT" | "ro-RO" | "ru-RU" | "sr-Latn-RS" | "sv-SE" | "ta-IN" | "th-TH" | "tr-TR" | "uk-UA" | "vi-VN" | "zu-ZA" | "en-US" | "en-AU" | "fr-BE" | "fr-CA" | "fr-CH" | "en-IE" | "nl-NL" | "nl-BE" | "es-ES" | "es-419" | "zh-HK" | "he-IL" | "en-NZ" | "et-EE" | "is-IS" | "lv-LV" | "mt-MT" | "sk-SK" | "sl-SL"
Language preference, defaults to English ('en').
details string
Miscellaneous details about the request.
createdAt string
The date at which you received the request and the SLA for completion should begin.
dataSiloIds array<string>
The set of data silo IDs that SHOULD be processed. When dataSiloIds is set, ONLY these data silos will be processed. dataSiloIds and ignoreDataSiloIds cannot both be set. When neither are set, the full set of data silos will be processed.
replyToEmailAddresses array<string>
The set of email addresses that should be included on CC for any outbound emails send to the data subject during the course of the request.
ignoreDataSiloIds array<string>
The set of data silo IDs that SHOULD NOT be processed. dataSiloIds and ignoreDataSiloIds cannot both be set. When neither are set, the full set of data silos will be processed. When ignoreDataSiloIds is set, the full set of data silos except these data silos will be processed.
emailReceiptTemplateId string
Specific email template to be sent to the end user upon request submission. When not provided, default template for workflow will be user.
skipWaitingPeriod boolean
When true, skip any waiting period associated with the workflow.
skipSendingReceipt boolean
When true, do not send an email receipt. This is not needed if isSilent=true, but can be useful when isSilent=false but no email receipt is desired.
skipEnrichmentChecks array<string>
Specify the IDs of the enrichers/preflights that should be skipped when running this request. When omitted, all enrichers/preflight checks defined for the workflow will be run.
requestId string
When restarting an existing request, specify the ID of the request to restart
completedRequestStatus stringenum: "FAILED_VERIFICATION" | "COMPLETED" | "CANCELED" | "SECONDARY_COMPLETED" | "REVOKED"
When uploaded a backlog of past DSRs, use this field to upload a request directly into a completed state.

Request Body Examples

Submit new Access DSR:

{
  "type": "ACCESS",
  "subject": {
    "coreIdentifier": "id-123456789",
    "email": "user@example.com"
  },
  "subjectType": "customer"
}

Submit new Erasure DSR with extra identifiers:

{
  "type": "ERASURE",
  "subject": {
    "coreIdentifier": "id-123456789",
    "email": "user@example.com",
    "emailIsVerified": true,
    "attestedExtraIdentifiers": {
      "email": [
        {
          "value": "another-email@example.com"
        }
      ],
      "custom": [
        {
          "value": "mbrook",
          "name": "username"
        }
      ]
    }
  },
  "subjectType": "customer"
}

Submit new DSR (all options):

{
  "type": "ACCESS",
  "subject": {
    "coreIdentifier": "id-123456789",
    "email": "user@example.com",
    "emailIsVerified": true,
    "attestedExtraIdentifiers": {
      "email": [
        {
          "value": "another-email@example.com"
        }
      ],
      "custom": [
        {
          "value": "mbrook",
          "name": "username"
        }
      ]
    }
  },
  "region": {
    "country": "US",
    "countrySubDivision": "US-CA"
  },
  "subjectType": "customer",
  "requestId": "e096a801-75bd-4296-ae6a-7c2553510500",
  "createdAt": "2022-03-30T04:56:00.143Z",
  "emailReceiptTemplateId": "9a558f86-51d4-4237-8c2d-494551991989",
  "skipEnrichmentChecks": [
    "b57972ed-736e-4141-8fdb-f5374a651aed"
  ],
  "dataSiloIds": [
    "72462d17-9089-4ab7-b74b-a0d6f6dfce7b"
  ],
  "ignoreDataSiloIds": [
    "9c1b56cb-5bf2-4528-8cd0-ee861401b704"
  ],
  "replyToEmailAddresses": [
    "test@transcend.io"
  ],
  "isSilent": true,
  "skipSendingReceipt": true,
  "skipWaitingPeriod": true,
  "isTest": false,
  "locale": "en",
  "completedRequestStatus": "COMPLETED",
  "details": "Additional details/notes about the request, if you'd like to add them",
  "attributes": [
    {
      "key": "attributeKey",
      "values": [
        "value1, value2, value3"
      ]
    }
  ]
}

Response

200 (OK)

application/json

The request was successfully submitted to Transcend to be processed. In order to check on this request in the future, you should store the request ID from this response.

Response Body

request object(required)

Response Body Example

Sample response body:

{
  "request": {
    "id": "da13d328-3f9d-40d5-9312-9f4fcf3ad0d2",
    "status": "COMPILING",
    "type": "ACCESS",
    "subjectType": "customer",
    "email": "user@example.com",
    "coreIdentifier": "id-123456789",
    "isSilent": true,
    "isTest": false,
    "replyToEmailAddresses": [],
    "link": "https://app.transcend.io/privacy-requests/incoming-requests/da13d328-3f9d-40d5-9312-9f4fcf3ad0d2"
  }
}

400 (Bad Request)

application/json

While this request passed authentication, the input is malformed. Please double-check that your code conforms to our API specification.

401 (Unauthorized)

application/json

There was a problem authenticating your request. This may be an issue with the Transcend API key ("authorization" header), or the Sombra API key ("x-sombra-authorization" header used for self-hosted gateways only).

409 (Conflict)

application/json

You're attempting to modify a DSR that is not in a modifiable state. For example, the DSR may have already completed, or been revoked.

429 (Too Many Requests)

application/json

You are sending requests too quickly and have hit our rate limit. If you hit this, you'll need to throttle your request velocity or try again later.

500 (Internal Server Error)

application/json

A 5xx error means there is either an issue with your self-hosted gateway, or a Transcend server is having issues. You check our system status at status.transcend.io. Please reach out to Transcend support if you're experiencing this error.

502 (Bad Gateway)

application/json

An upstream service on Transcend's side is having issues. You check our system status at status.transcend.io. Please reach out to Transcend support if you're experiencing this error.