Rights protocols

Request Types

Response Status

Each response can have a status that communicates to the Ketch platform how to handle the activity. The
status is case-sensitive.

Common objects

Callback

The Callback object defines a URL and associated headers to be used for communicating information.
The protocol for communicating with the Callback is defined for every object that uses the Callback.

{
  "url": "https://dsr.ketch.com/callback",
  "headers": {
    "Authorization": "$auth"
  }
}

Fields

namerequired?description
urlyesURL of the callback endpoint
headersnomap of headers to send to the callback endpoint

Document

The Document object defines a way of providing document data to the Ketch platform.

As a Callback

The Document object can look like a Callback object which allows Ketch to download
the document using a simple HTTP GET.

{
  "url": "https://dsr.controller.com/get/my/document",
  "headers": {
    "Authorization": "$auth"
  }
}

See Callback for more details of this Document subtype.

As an embedded object

The Document object can provide the data directly in the value.

{
  "data": "standard-base64-encoded-data",
  "headers": {
    "Content-Type": "application/json"
  }
}

Here, the document is returned directly in the response/event using base64-encoded data. The
Content-Type header is required so Ketch knows the mime type
of data received. The only supported content types are application/json and application/pdf. File size is
limited to 3.5Mb.

JSON Data

JSON document data is combined across all callback requests for a given DSR request using merge patches as defined
in RFC7396. The total response data across all callbacks is
limited to 1MB.

Fields

namerequired?description
datayesStandard base64-encoded data
headersyesmap of headers for the data
headers.Content-Typeyesmime type of the data

Identity

The Identity object describes the identity of a Data Subject.

{
  "identitySpace": "account_id",
  "identityFormat": "raw",
  "identityValue": "123"
}

Fields

namerequired?description
identitySpaceyesIdentity space code setup in Ketch
identityFormatnoFormat of the identity value (raw, md5, sha1). Default is raw.
identityValueyesValue of the identity

Subject

The Subject object describes the Data Subject making the request. The fields type, email, city, and description are
read only. Any empty subject values will be ignored when patching the subject. Additional properties may exist
in this object depending on the subject type.

{
  "type": "employee",
  "email": "[email protected]",
  "firstName": "Test",
  "lastName": "Subject",
  "addressLine1": "123 Main St",
  "addressLine2": "",
  "city": "Anytown",
  "stateRegionCode": "MA",
  "postalCode": "10123",
  "countryCode": "US",
  "description": "Restrict my data",
  "formData": {
    "customFormField1": "value1",
    "customFormField2": "value1"
  }
}

Fields

namerequired?description
typenoType of the data subject (customer, employee, etc.)
emailyesEmail address provided by the Data Subject
firstNameyesFirst name provided by the Data Subject
lastNameyesLast name provided by the Data Subject
addressLine1noAddress line 1 provided by the Data Subject
addressLine2noAddress line 2 provided by the Data Subject
citynoCity provided by the Data Subject
stateRegionCodenoState/region code (e.g., CA) provided by the Data Subject
postalCodenoZip/postal code provided by the Data Subject
countryCodenoTwo-character ISO country code (e.g., US) provided by the Data Subject
descriptionnoFree-text description provided by the Data Subject
formDatanoMap containing additional form data that have been added via custom Form Fields

Response Augmentation

All Response and Event objects support augmenting the Data Subject Request, whether adding context variables
to the workflow, updating the data subject, mutating identities, adding results/internal documents or adding
messages to the request conversation.

Add context variables

To add or update context variables, return the context property. Context is a map from the context variable
code (string) to the value (string, integer or boolean).

Update data subject

Map containing additions or changes to subject values Data Subject. To add or update data subject
values, set the key and value.

Mutate identities

To add identities, return additional Identities in the identities property.

Add results

To add results that should be made available to the Data Subject, return result documents in the results property.

Add documents

To add documents that should be available internally to a Ketch operator, but not the Data Subject, return result documents
in the documents property.

Add messages to conversation

To add messages to the Data Subject Request conversation, return an array of JSON Messages in the messages property.

Status

The status of a Request progresses through the following state/activity diagram:

Note that multiple Status events can be received with each status. For example, a callback may be called daily with
a status of in_progress until finally the final status is sent with status of completed.

If a Response does not include a return status of completed, cancelled or denied, then a subsequent StatusEvent
event MUST be sent to the callbacks with one of those statuses. Otherwise, the request will be marked as failed after
some time.

Status code

namedescription
unknownthe status is unknown
pendingthe request is pending approval
in_progressthe request is in progress
completedthe request has been completed
cancelledthe request has been cancelled
deniedthe request has been denied

The status code is case sensitve.

Reason

statusreasondescription
anyunknown (default)the reason for the status is unknown/other
pendingneed_user_verificationthe status is pending because the Data Subject needs to complete identity verification
pendingpendingthe request is pending
completedrequestedthe request has been forwarded for execution
completedno_matchthe request was completed, but there is no match for the Data Subject
completedinsufficient_identificationthe Data Subject was not sufficiently identified
completedexecutedthe request has been executed
completedexecuted_direct_subject_deliverythe request completed and data will be delivered directly to Data Subject email or app portal
deniedno_matchthere is no match for the Data Subject
deniedinsufficient_identificationthe Data Subject was not sufficiently identified
deniedinsufficient_verificationthe Data Subject has insufficiently completed identity verification
deniedclaim_not_coveredthe claim is not covered
deniedoutside_jurisdictionthe Data Subject is outside the covered jurisdiction
deniedtoo_many_requeststhe Data Subject has made too many requests
deniedsuspected_fraudthe request is suspected fraud
deniedinvalid_credentialsthe request failed due to invalid credentials
deniedinsufficient_permissionthe request failed due to insufficient permission
deniedinternal_app_errorthe request failed due to an internal app error
deniedsla_expirythe request failed due to SLA expiry