To initiate a data subject request use this endpoint.

POST

/v1/data-subject-request

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

authorizationstring
An API key generated from the Transcend dashboard: https://app.transcend.io/infrastructure/api-keys.
x-sombra-authorizationstring
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-typestring
Specify content-type: application/json for a JSON response from the Transcend API.

application/json

typestringmin-length:1(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).
subjectobject(required)
attributesarray<object>
Key-value pairs used to label data subject requests. These are Custom Fields in Transcend, and formerly known as Attributes.
subjectTypestringmin-length:1(required)
The class of data subject, e.g. "customer", "subscriber".
regionobject
Specify the region that the request is submitting from. See https://github.com/transcend-io/privacy-types/blob/main/src/isoConstants/iso3166-1.ts
isSilentbooleandefault:false
When true, no emails will be sent to the data subject (including confirmation emails).
isTestbooleandefault:false
When true, the request will be flagged as a test request. (useful for auditing purposes). Test requests still operate on your live integrations.
localestringdefault:enmin-length:1enum:"en" | "ar" | "fr" | "es" | "de" | "it" | "ja" | "ru" | "af" | "bg" | "zh" | "hr" | "cs" | "da" | "fi" | "el" | "hi" | "hu" | "ko" | "lt" | "ms" | "mr" | "nb" | "pl" | "pt" | "ro" | "sr" | "sv" | "ta" | "th" | "tr" | "uk" | "vi" | "zu" | "he" | "nl" | "et" | "is" | "lv" | "mt" | "sk" | "sl" | "fil" | "bs" | "ca" | "eu" | "gl" | "dv" | "ur" | "sq" | "am" | "hy" | "az" | "bn" | "fa-AF" | "tl" | "ka" | "gu" | "ht" | "ha" | "ga" | "kn" | "kk" | "mk" | "ml" | "mn" | "ps" | "pa" | "si" | "so" | "sw" | "te" | "uz" | "cy" | "ar-AE" | "fr-FR" | "de-DE" | "de-AT" | "de-CH" | "it-IT" | "it-CH" | "af-ZA" | "bg-BG" | "zh-CN" | "zh-TW" | "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" | "ms-SG" | "mr-IN" | "nb-NO" | "pl-PL" | "pt-BR" | "pt-PT" | "ro-RO" | "ru-RU" | "sr-Latn-RS" | "sr-Cyrl-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-AR" | "es-CR" | "es-CL" | "es-CO" | "es-MX" | "es-419" | "zh-HK" | "he-IL" | "en-NZ" | "et-EE" | "is-IS" | "lv-LV" | "mt-MT" | "sk-SK" | "sl-SL" | "fil-PH" | "sq-AL" | "sq-MK" | "sq-XK" | "am-ET" | "hy-AM" | "az-AZ" | "bn-BD" | "bn-IN" | "bs-BA" | "bs-Cyrl-BA" | "bs-Latn-BA" | "ca-ES" | "ca-AD" | "ca-FR" | "ca-IT" | "tl-PH" | "ka-GE" | "gu-IN" | "ht-HT" | "ha-NG" | "ha-NE" | "ha-GH" | "ga-IE" | "kn-IN" | "kk-KZ" | "mk-MK" | "ml-IN" | "mn-MN" | "ps-AF" | "pa-Guru-IN" | "pa-Arab-PK" | "si-LK" | "so-SO" | "so-DJ" | "so-ET" | "so-KE" | "sw-KE" | "sw-TZ" | "sw-UG" | "sw-CD" | "te-IN" | "ur-PK" | "ur-IN" | "uz-UZ" | "cy-GB" | "eu-ES" | "gl-ES"
Language preference, defaults to English ('en').
detailsstringmin-length:1
Miscellaneous details about the request.
createdAtstringmin-length:1
The date at which you received the request and the SLA for completion should begin.
dataSiloIdsarray<string>
The set of data system IDs that SHOULD be processed. When dataSiloIds is set, ONLY these data systems will be processed. dataSiloIds and ignoreDataSiloIds cannot both be set. When neither are set, the full set of data systems will be processed.
replyToEmailAddressesarray<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.
ignoreDataSiloIdsarray<string>
The set of data system IDs that SHOULD NOT be processed. dataSiloIds and ignoreDataSiloIds cannot both be set. When neither are set, the full set of data systems will be processed. When ignoreDataSiloIds is set, the full set of data systems except these data systems will be processed.
emailReceiptTemplateIdstring (uuid)
Specific email template to be sent to the end user upon request submission. When not provided, default template for workflow will be user.
skipWaitingPeriodboolean
When true, skip any waiting period associated with the workflow.
skipSendingReceiptboolean
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.
skipEnrichmentChecksarray<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.
requestIdstring (uuid)
When restarting an existing request, specify the ID of the request to restart
completedRequestStatusstringmin-length:1enum:"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"
      ]
    },
    {
      "key": "Source",
      "values": [
        "Mobile iOS App"
      ]
    }
  ]
}

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

requestobject(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).

413 (Request Entity Too Large)

application/json

The request body is too large. JSON and raw bodies must be less than 50MB. URL encoded bodies must be less than 30MB.

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.

Response Headers

Retry-Afterinteger
X-RateLimit-Limitinteger
X-RateLimit-Remaininginteger
X-RateLimit-Resetinteger

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.