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

Header Parameters

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.

Request Body

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
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:
When true, no emails will be sent to the data subject (including confirmation emails).
isTestbooleandefault:
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" | "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').
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 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.
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 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.
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"
      ]
    }
  ]
}

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

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.

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.