Ingress API-Dokumentation für DSRs

Last updated: July 22, 2026

Allgemein

Die Kertos-Plattform bietet Unterstützung zur Erstellung von Anfragen zur betroffenen Person über den folgenden REST-Endpunkt:

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

Der Endpunkt erwartet eine HTTP-POST-Anfrage mit einer Nutzlast, die dem folgenden Format entspricht:

{
    "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
}

 

Erklärung der Eigenschaften:

  • request_actions Ein Array, das angibt, welche Arten von Anfragen erstellt werden sollen. Wenn mehrere Werte übergeben werden, werden mehrere Anfragen erstellt.

  • data_subject Ein Objekt, das Informationen über die betroffene Person (die anfordernde Person) enthält.

  • first_name Optional: Der Vorname des anfordernden Betroffenen

  • last_name Optional: Der Nachname des anfordernden Betroffenen

  • subject_type Der Subjekttyp der anfordernden betroffenen Person. Dieser String muss einem der in Ihrer Kertos-Instanz konfigurierten Datensubjekt-Anfragetypen entsprechen. Standardmäßig sind dies die folgenden: "Applicants" , "Customers" , "Employees" , "Prospects" , "Service Providers" , "Suppliers" , "Website Visitors" , "Other"

  • identifiers Ein Array, das Objekte enthält, die Informationen zu den Identifikatoren, die zur Identifizierung der erstellten betroffenen Person verwendet werden sollen, halten.

    • identifier_type Der Typ des Identifikators. Unterstützte Werte sind "Email" , "PhoneNumber" und "AdditionalIdentifier" .

    • identifier Der Identifikator selbst. Zum Beispiel eine E-Mail-Adresse oder eine Telefonnummer, je nach dem bereitgestellten identifier_type.

    • is_verified Gibt an, ob der Identifikator bereits verifiziert wurde. Dies ist relevant, um zu bestimmen, welche Identifikatoren noch verifiziert werden müssen, wenn der E-Mail-Verifizierungsablauf verwendet wird. Insbesondere beim Erstellen von Anfragen aus Systemen mit verifizierten Daten sollte dieses Flag auf wahr gesetzt werden.

    • is_used_for_communication Gibt an, dass dieser Identifikator verwendet werden sollte, um die anfordernde betroffene Person über die Fertigstellung der Anfrage zu informieren. Wenn is_used_for_communication auf mehr als einem Identifikator auf true gesetzt ist, führt dies zu einer 400-Antwort.

    • received_at Ein Datum-Uhrzeit-String, der angibt, wann die Anfrage der betroffenen Person ursprünglich empfangen wurde. Dieses Feld wird verwendet, um die Frist der erstellten Anfrage zu bestimmen.

    • skip_verification_email Wenn hier true übergeben wird, wird keine E-Mail zur Identitätsverifizierung an die betroffene Person gesendet. Bitte stellen Sie sicher, dass Sie wirklich eine E-Mail an die betroffene Person senden möchten, wenn Sie dieses Feld auf false setzen.

    • channel Dieser Kanal, über den die Anfrage empfangen wurde.

    • inquiry Optionaler Anfrage-Text. Wenn für die Anfrage zusätzlicher Kontext bereitgestellt werden soll, kann dieses Feld verwendet werden.

Authentifizierung

Zur Authentifizierung wird ein Header-basierter Ansatz verwendet. Die Plattform erwartet, dass bei jeder Anfrage an das Endpunkt ein API-Key im Anfrage-Header mit dem Namen X-API-KEY.

API-Schlüssel können im Einstellungsbereich Ihrer Kertos-Instanz unter https://app.kertos.io/settings/connections

Beispielanfragen

Einfache Anfrage

Dies ist ein Beispiel für eine Anforderungsnutzlast, die verwendet werden kann, um eine einfache Betroffenenanfrage zu erstellen. Die Anfrage wird für eine betroffene Person erstellt, die über die E‑Mail‑Adresse „john.doe@kertos.io“ identifiziert wird.

{
  "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
      }
    ]
  }
}

Mehrfach-Identifikationsanfrage

Wenn eine betroffene Person mehrere relevante Identifikatoren innerhalb Ihrer Organisation (z. B. eine E-Mail-Adresse und eine Telefonnummer) angeben kann, können Sie ebenfalls eine Anfrage mit mehreren Identifikatoren gemäß dem folgenden Beispiel erstellen. Diese Nutzlast erzeugt eine Löschanfrage für eine betroffene Person, die eine E-Mail-Adresse und eine Telefonnummer als Identifikatoren hat.

{
  "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-Antwortcodes

Die folgenden HTTP-Antwortcodes können von Ihrem Webhook gesendet werden, um Kertos anzuzeigen, dass etwas schiefgelaufen ist:

200 Data Subject Requests Created
Zeigt an, dass die Betroffenenanfrage erfolgreich erstellt wurde

400 Invalid Input
Zeigt an, dass die Eingabe fehlerhaft ist und keine Betroffenenanfragen erstellt werden konnten