Ingress API Docs for DSRs

General

The Kertos platform offers support to create data subject requests via the following REST endpoint:

POST https://api.kertos.io/api/v1/external/data_subject_requests/

The endpoint expects a HTTP POST request with a payload adhering to the following format:

{
    "requested_actions": ["access" | "delete"],
    "data_subject":   "data_subject": {
        "first_name": string,
        "last_name": string,
        "subject_type": string,
        "identifiers": [
            {
                "identifier_type": "Email" | "PhoneNumber" | "AdditionalIdentifier",
                "identifier": string,
                "is_verified": boolean,
                "is_used_for_communication": boolean
            }
        ]
    },
    "received_at": string <date-time>,
    "skip_verification_email": boolean,
    "channel": "email" | "phone" | "mail" | "fax" | "website" | "app" | "other",
    "inquiry": string
}

Explanation of properties:

• request_actions  An array indicating which types of requests should be created. If multiple values are passed, multiple requests are created.
• data_subject An object containing information on the data subject (the requesting individual)
• first_name Optional: The first name of the requesting data subject
• last_name Optional: The last name of the requesting data subject
• subject_type The subject type of the requesting data subject. This string needs to correspond to one of the data subject request types configured in your Kertos instance. By default, these are  the following: "Applicants" , "Customers" , "Employees" , "Prospects" , "Service Providers" , "Suppliers" , "Website Visitors" , "Other"
• identifiers An array containing objects holding information on the identifiers that should be used to identify the created data subject
  • identifier_type The type of the identifier. Supported values are "Email" , "PhoneNumber"  and "AdditionalIdentifier" .
  • identifier The identifier itself. For example and email address or a phone number depending on the provided identifier_type.
  • is_verified Indicates if the identifier has been previously verified. This is relevant to determine which identifiers still need verification if the email verification flow is used. Especially when creating requests from systems with verified data, this flag should be set to true.
  • is_used_for_communication Indicates that this identifier should be used to inform the requesting data subject about the request having been completed. Having is_used_for_communication set to true on more than one identifier will yield a 400 response.
  • received_at A date-time string indicating when the data subject request was initially received. This field is used to determine the deadline of the created request.
  • skip_verification_email If true is passed here, no email for identity verification is sent to the data subject. Please make sure you actually want to send an email to the data subject if setting this field to false.
  • channel This channel through which the request was received.
  • inquiry Optional inquiry text for the request. If additional context is supposed to be provided for the request, this field can be used.

Authentication

For authentication, a header-based approach is used. The platform expects an an API-key present on every request made to end endpoint in a request header called X-API-KEY.

API keys can be created in the settings section of your Kertos instance under https://app.kertos.io/settings/api.

Request samples

Simple request

This is an example for a request payload that can be used to create a basic data subject request. The request is created for a data subject that is identified via the email address “john.doe@kertos.io”.

{
  "requested_actions": [
    "delete"
  ],
  "received_at": "2020-01-01T00:00:00Z",
  "skip_verification_email": false,
  "channel": "phone",
  "data_subject": {
    "first_name": "John",
    "last_name": "Doe",
    "subject_type": "customer",
    "identifiers": [
      {
        "identifier_type": "Email",
        "identifier": "john.doe@kertos.io",
        "is_verified": true,
        "is_used_for_communication": true
      }
    ]
  }
}

Multi Identifier Request

If a data subject can half multiple relevant identifiers within your organisation (for example an email address and a phone number), you can also create a request with multiple identifiers according to the following example. This payload will create a deletion request with a data subject that has an email address and a phone number as identifiers.

{
  "requested_actions": [
    "delete"
  ],
  "received_at": "2020-01-01T00:00:00Z",
  "skip_verification_email": false,
  "channel": "phone",
  "data_subject": {
    "first_name": "John",
    "last_name": "Doe",
    "subject_type": "customer",
    "identifiers": [
      {
        "identifier_type": "Email",
        "identifier": "john.doe@kertos.io",
        "is_verified": true,
        "is_used_for_communication": true
      },
      {
        "identifier_type": "PhoneNumber",
        "identifier": "+491626926678",
        "is_verified": true,
        "is_used_for_communication": false
      }
    ]
  }
}

HTTP Response Codes

The following HTTP response codes can be sent by your webhook to indicate to Kertos that something has gone wrong:

200 Data Subject Requests Created
Indicates that the data subject request was created successfully

400 Invalid Input
Indicates that the input is malformed and no data subject requests could be created