---
title: KYC Magic Link
description: Führt den Identifikationsprozess in Mexiko durch, sammelt nationale Ausweisdokumente (INE) und Gesichtsbiometrie über eine gehostete Journey, die über einen einzigartigen Link verteilt wird.
canonical: https://developer.unico.io/de/dual-api/products/sign-up/kyc-magic-link/index
locale: de
generated_by: markdown-export
---

- [/de/](/de/)
- [Entwickeln](/de/dual-api/products/)
- Regionaler Leitfaden
- KYC Magic Link

**Auf dieser Seite# KYC Magic Link

Separater regionaler VertragDieser Anwendungsfall verwendet **nicht** den Unico-Endpunkt `POST /v1/process` und auch nicht den API-Vertrag. Die Integration erfolgt mit **Trully.ai** (Host `api.trully.ai`), mit **Authentifizierung über `x-api-key`** statt Bearer JWT und einem **proprietären Antwortschema**. Für andere Länder verwenden Sie Onboarding (Global).
### Was dieser Anwendungsfall löst​

KYC Magic Link löst die Herausforderung, den Identifikationsprozess in Mexiko durchzuführen, nationale Ausweisdokumente (INE) und Gesichtsbiometrie zu sammeln. Mit einer von Unico gehosteten Journey eliminieren Sie den Front-End-Entwicklungsaufwand durch einen Link, der über Ihre eigenen Kanäle (WhatsApp, SMS, E-Mail) versendet wird.
**Verwenden Sie diesen Anwendungsfall, wenn:**

Sie in **Mexiko** tätig sind und das verwendete Ausweisdokument der **INE (obligatorisch)** ist.

**Verwenden Sie diesen Anwendungsfall nicht, wenn:**

Der Benutzer sich außerhalb Mexikos befindet oder andere Dokumente verwendet → schauen Sie sich die anderen Onboarding-Anwendungsfälle an.

### Beteiligte Capabilities​

Pipeline, die innerhalb eines einzigen Prozesses ausgeführt wird:
[Document Capture (INE)](/de/capabilities/document-reuse-and-capture)[Liveness](/de/capabilities/liveness)[Risk Fraud Classification](/de/capabilities/fraud-risk-classification)[Identity Verification](/de/capabilities/identity-verification)
CapabilityErforderlichRolle im Ablauf**Document Capture**ErforderlichErfasst das INE-Dokumentenbild. Die Wiederverwendung von Dokumenten ist in diesem Anwendungsfall **nicht verfügbar** — jede Sitzung erfordert eine neue Erfassung.**Liveness**ErforderlichLiveness-Prüfung — obligatorisches Selfie, das den Prozess verankert.**Risk Fraud Classification**ErforderlichGleicht Verhaltenssignale ab, um das mit der CPF verbundene Betrugsrisiko zu kennzeichnen.**Identity Verification**Optional (falls vertraglich vereinbart)Überprüft, ob das Transaktionsgesicht zum Inhaber des angegebenen staatlichen Identifikators gehört, unter Verwendung der Identitätsbasis von Unico und zusätzlicher Signale.**[RENAPO-Verifizierung](/de/capabilities/renapo-verification)**Optional (falls vertraglich vereinbart)Fragt RENAPO, das nationale Bevölkerungsregister Mexikos, mit der CURP des Benutzers ab und gibt den Registereintrag zusammen mit dem Ergebnis der Identitätsprüfung zurück.
### Voraussetzungen​

**API-Schlüssel**  — bereitgestellt von Ihrem Onboarding-Projektmanager bei Unico. Wird im Header `x-api-key` gesendet.
**Öffentlicher HTTPS-Endpunkt** zum Empfang von Webhooks (optional, aber empfohlen).
**CORS-Konfiguration** — erlauben Sie die Ursprünge `https://verification.unico.app` (Produktion) und `https://verification.uat.unico.app` (Sandbox) auf dem Server, der den Webhook empfängt.

### Schritt-für-Schritt-Implementierung​

Im Gegensatz zu anderen Anwendungsfällen hat Magic Link **kein `flow`-Feld** — die Integration erfolgt direkt mit der Trully-API. Der Endpunkt erstellt einen einzigartigen Verifizierungslink, den Sie dem Benutzer über Ihren eigenen Kanal zukommen lassen.
### 1. Magic Link erstellen​

**Endpunkt:** `POST https://sandbox.trully.ai/v2/magic-link`
**Header:**
HeaderErforderlichBeschreibung`x-api-key`JaAPI-Schlüssel, bereitgestellt von Ihrem Onboarding-Projektmanager bei Unico.`Content-Type`Ja`application/json`
**Body (application/json):**
FeldTypErforderlichBeschreibung`external_id`stringNeinEin externer Bezeichner für die Anfrage, der für Tracking- und Referenzzwecke verwendet wird.`metadata`objectNeinContainer für Konfigurationsparameter.`metadata.phone`stringNeinTelefonnummer des Benutzers im internationalen Format (z. B. `521234567890`).`metadata.redirect_url`stringNeinURL, zu der der Benutzer nach Abschluss des KYC-Prozesses weitergeleitet wird.`metadata.webhook_url`stringNeinURL, an die die KYC-Prozessdaten nach Abschluss des KYC-Prozesses gesendet werden. Dieser Webhook wird auf der Client-Seite aufgerufen. Aus Sicherheitsgründen sollte der Endpunkt HTTPS verwenden. Die Komponente wartet eine Minute auf eine Antwort Ihres Webhook-Servers — danach bricht sie die Kommunikation ab. Der Prozess wird durch die Webhook-Kommunikation in keiner Weise beeinträchtigt. Stellen Sie sicher, dass Sie `https://verification.unico.app` und `https://verification.uat.unico.app` in Ihrer CORS-Konfiguration für Produktion bzw. Sandbox zulassen.`metadata.track_webhook_url`stringNeinURL, an die jeder vom Benutzer verarbeitete KYC-Schritt gesendet wird (siehe Webhook-Ereignisse unten). Dieser Webhook wird auf der Client-Seite aufgerufen. Aus Sicherheitsgründen sollte der Endpunkt HTTPS verwenden. Die Komponente wartet eine Minute auf eine Antwort Ihres Webhook-Servers — danach bricht sie die Kommunikation ab. Der Prozess wird durch die Webhook-Kommunikation in keiner Weise beeinträchtigt. Stellen Sie sicher, dass Sie `https://verification.unico.app` und `https://verification.uat.unico.app` in Ihrer CORS-Konfiguration für Produktion bzw. Sandbox zulassen.
`data.step` (gesendet an `track_webhook_url`) meldet dieselben Schritte, die von Webhook V2 verfolgt werden — siehe die [Tabelle der unterstützten Schritte](#webhook-v2) unten.
**Beispielanfrage:**
```
curl -X POST https://sandbox.trully.ai/v2/magic-link \  -H "x-api-key: $TRULLY_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "external_id": "user-mx-12345",    "metadata": {      "phone": "521234567890",      "redirect_url": "https://app.client.com.mx/kyc-done",      "webhook_url": "https://app.client.com.mx/webhook/result",      "track_webhook_url": "https://app.client.com.mx/webhook/track"    }  }'
```

### 2. Token und Link-URL empfangen​

**Antwortfelder:**
FeldTypBeschreibung`data.external_id`string (nullable)Ein externer Bezeichner für die Anfrage, der für Tracking- und Referenzzwecke verwendet wird.`data.created_on`string (date-time)Das Datum, an dem der Magic Link erstellt wurde.`data.is_active`booleanWenn `true`, ist der Magic Link aktiv.`data.token`stringDas Token des Magic Links, das verwendet wird, um die KYC-Prozesse mit dem Magic Link zu verknüpfen.`data.magic_link_url`string (URI)Die Magic-URL, um den KYC-Prozess zu starten.`data.metadata.redirect_url`string (nullable)URL, zu der der Benutzer nach Abschluss des KYC-Prozesses weitergeleitet wird.`data.metadata.webhook_url`string (nullable)URL, an die die KYC-Prozessdaten nach Abschluss gesendet werden. Dieser Webhook wird auf der Client-Seite aufgerufen.`data.metadata.track_webhook_url`string (nullable)URL, an die jeder vom Benutzer verarbeitete KYC-Schritt gesendet wird. Dieser Webhook wird auf der Client-Seite aufgerufen.`data.version`stringDie Version des Magic Links.`version`stringDie Version der API, die die Anfrage verarbeitet hat, nützlich zur Verfolgung von Änderungen und Kompatibilität.`status`stringEine textuelle Darstellung des Antwortstatus, die den Erfolg oder Misserfolg des Vorgangs anzeigt.`status_code`integerDer HTTP-Statuscode der Antwort, der einen standardisierten Indikator für das Ergebnis der Anfrage liefert.`request_date`string (date-time)Datum und Uhrzeit der Anfrage im ISO-8601-Format.`request.metadata.redirect_url`string (nullable)URL, zu der der Benutzer nach Abschluss des KYC-Prozesses weitergeleitet wird (Echo der Anfrage).`request.metadata.webhook_url`string (nullable)URL, an die die KYC-Prozessdaten nach Abschluss gesendet werden (Echo der Anfrage).`request.metadata.track_webhook_url`string (nullable)URL, an die jeder vom Benutzer verarbeitete KYC-Schritt gesendet wird (Echo der Anfrage).
**Beispielantwort:**
```
{  "data": {    "external_id": null,    "created_on": "2025-07-28T18:11:54.430048399Z",    "is_active": true,    "token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",    "magic_link_url": "https://verification.uat.unico.app/link/v2/3f6dbcc1-49ba-4935-be90-dd8dd59b5530",    "metadata": {      "redirect_url": null,      "webhook_url": null,      "track_webhook_url": null    },    "version": "v2"  },  "version": "v1.4.2",  "status": "ok",  "status_code": 200,  "request_date": "2025-07-28T18:11:54+0000",  "request": {    "metadata": {      "redirect_url": null,      "webhook_url": null,      "track_webhook_url": null    }  }}
```

**Fehlerantworten — POST /v2/magic-link**CodeMeldungBeschreibung`400 Bad Request``data provided in the field is invalid`Ungültige Datenstruktur oder Feldwerte in der Anfrage-Payload. Überprüfen Sie Pflichtfelder und Formate.`403 Forbidden``Forbidden`API-Schlüssel fehlt, ist abgelaufen oder hat keine Berechtigung. Überprüfen Sie den Header `x-api-key`.`500 Internal Server Error``internal server error`Serverseitiger Verarbeitungsfehler. Wiederholen Sie den Vorgang mit exponentiellem Backoff. Bei Persistenz wenden Sie sich an den Support.**Beispiel 400-Antwort:**```
{  "data": {    "error": "data provided in the field is invalid"  },  "version": "v1.4.2",  "status": "bad request",  "status_code": 400,  "request_date": "2025-07-28T20:22:29+0000",  "request": {    "metadata": null  }}
```

### 3. magic_link_url an den Benutzer verteilen​

Senden Sie per WhatsApp, SMS, E-Mail oder betten Sie den Link ein. Der Benutzer öffnet den Link auf seinem eigenen Gerät und schließt die gehostete Journey ab.
Wenn Sie die Journey lieber in Ihre eigene App einbetten möchten, anstatt den Link im Browser zu öffnen, können Sie dies über WebView oder CustomTab tun. Referenz-PoCs:

**Android/Kotlin:** [TrullyAi-AndroidMagicLink](https://github.com/unico-labs/TrullyAi-AndroidMagicLink)
**React Native:** [TrullyAI-ReactNativeMagicLink](https://github.com/unico-labs/TrullyAI-ReactNativeMagicLink)

### 4. Ergebnis empfangen​

Sie haben volle Flexibilität bei der Entscheidung, wie Sie das Endergebnis des KYC-Prozesses empfangen möchten — wählen Sie die Strategie, die am besten zur Architektur Ihres Systems passt. Sie können das Ergebnis aktiv abfragen (GET) oder passiv über Benachrichtigungen empfangen (Webhook).
**Option A — Aktives Polling via GET**
Rufen Sie das Ergebnis ab, indem Sie `GET /v2/history/request?magic_link_token={token}` aufrufen (siehe [Polling via GET](#polling-via-get) unten). Die endgültige Entscheidung wird in `data.response.unico.result` befüllt.
Best Practice für GETVerwenden Sie anstelle von periodischem Polling ab dem Moment der Linkerstellung die Tracking-Webhooks (siehe [Webhook V2](#webhook-v2) unten), um genau zu wissen, wann Sie abfragen sollten. Sobald Sie den Schritt `form_decision_maker` empfangen, ist dies der exakte, sichere Zeitpunkt, um diesen GET-Aufruf auszulösen.
**Option B — Automatischer Empfang via Webhook**
Lassen Sie Ihr System automatisch benachrichtigen, sobald das Endergebnis bereit ist (siehe [Webhook V2](#webhook-v2) unten). Es stehen zwei Versionen zur Verfügung:

**Webhook V1** — Sie erhalten das Ergebnis an der URL, die bei der Erstellung des Tokens in `metadata.webhook_url` gesendet wurde.
**Webhook V2** — vorab mit Ihrem Onboarding-PM konfiguriert. Sie erhalten das endgültige Urteil, indem Sie auf das Ereignis `MAGIC_LINK_RESULTS` lauschen.

Resilienz — FallbackWenn Webhook (Option B) Ihre primäre Methode ist, implementieren Sie zusätzlich die GET-Abfrage (Option A) als Fallback. So können Sie das Ergebnis über Abgleichsroutinen wiederherstellen, falls Netzwerkfehler oder vorübergehende Serverausfälle auftreten oder ein Webhook nicht korrekt verarbeitet werden konnte.

### Polling via GET​

**Endpunkt:** `GET https://sandbox.trully.ai/v2/history/request`
**Abfrageparameter:**
ParameterTypErforderlichBeschreibung`magic_link_token`stringJaToken, das bei der Erstellung des Magic Links zurückgegeben wurde.
**Header:**
HeaderErforderlichBeschreibung`x-api-key`JaAPI-Schlüssel, bereitgestellt von Ihrem Onboarding-Projektmanager bei Unico.
**Beispielanfrage:**
```
curl "https://sandbox.trully.ai/v2/history/request?magic_link_token=$TOKEN" \  -H "x-api-key: $TRULLY_API_KEY"
```

**Beispielantwort:**
```
{  "data": {    "images": {      "document_image": "/9j/4ASu7bmV[...]fyPjOKfgif//Z",      "document_image_back": "/9j/4ASu7bmV[...]fyPjOKfgif//Z",      "selfie": "/9j/4ASu7bmV[...]fyPjOKfgif//Z"    },    "response": {      "curp": {        "age": 58,        "curp": "GOCJ850627HDFRRL09",        "date_of_birth": "14/11/1956",        "deceased": false,        "gender": "M",        "government_name": "LUKE SKYWALKER",        "government_valid": true,        "is_mexican": true,        "name_to_CURP_valid": true,        "state_iso": "MX-NLE",        "state_of_birth": "Nuevo León"      },      "document": {        "back": {          "cic": "237457894",          "citizen_id": "237457894",          "mrz": "IDMEX999999999999<9 VADER<SKYWALKER<<LUKE"        },        "details": {          "detected": true,          "document_id": 229928,          "forensics": { "is_valid": "no" }        },        "front": {          "face_analysis": {            "face_id": 237437,            "face_id_v2": 199068,            "first_seen": "12/22/2022, 18:54:09",            "inquiry_date": "07/28/2025, 20:53:12",            "last_seen": "07/28/2025, 18:47:46",            "last_seen_by_your_company": "07/24/2025, 21:38:21",            "match": true,            "match_fraud_flag": true,            "seen_by_your_company": true,            "seen_different_companies": 46,            "times_seen_by_your_company": 3,            "times_seen_last_month": 111,            "unique_face_id_v2": 126880,            "warnings": {              "external_id": "User found in the company with other external_ids: ['abc-123']"            }          },          "information": {            "address": { "text": "DOMICILIO/ADDRESS, HARLINGEN, TX 78552", "valid": false },            "birthdate": { "text": "14/11/1956", "valid": true },            "complete_name": { "text": "LUKE SKYWALKER", "valid": true },            "curp": { "text": "GOCJ850627HDFRRL09", "valid": true },            "electoral_key": { "text": "GRCRSN82031007M500", "valid": true },            "last_name": { "text": "SKYWALKER", "valid": true },            "mother_last_name": { "text": "ORGANA", "valid": true },            "name": { "text": "LUKE", "valid": true },            "registration_year": { "text": "1998", "valid": true },            "sex": { "text": "H", "valid": true },            "valid_thru": { "text": "2027", "valid": true }          }        }      },      "face_match": false,      "label": null,      "reason": null,      "request_id": "d1kxp9ah8f0s71uv9zx0",      "selfie": {        "face_id": 237436,        "face_id_v2": 4378,        "first_seen": "02/05/2025, 02:36:19",        "first_seen_image": true,        "inquiry_date": "07/28/2025, 20:52:49",        "last_seen": "07/28/2025, 20:52:51",        "last_seen_by_your_company": "07/23/2025, 18:14:27",        "match": true,        "match_fraud_flag": true,        "seen_by_your_company": true,        "seen_different_companies": 2,        "times_seen_by_your_company": 2,        "times_seen_last_month": 7,        "unique_face_id_v2": 494,        "warnings": {}      },      "unico": {        "process_id": "d333dfac-9ddb-4066-8e2c-44eaf4c86b4a",        "result": "PROCESS_RESULT_LIVE"      }    },    "user_id": ""  },  "request_date": "2025-07-28T20:53:38",  "status": "Request fulfilled, document follows",  "status_code": 200,  "version": "v3.6.0"}
```

**Antwortfelder:**
**Stammebene:**
FeldTypBeschreibung`status`stringTextuelle Darstellung des Antwortstatus.`status_code`integerHTTP-Statuscode.`request_date`string (date-time)Datum und Uhrzeit der Anfrage.`version`stringAPI-Version, die die Anfrage verarbeitet hat.`data.user_id`stringDie in der ursprünglichen Anfrage festgelegte Benutzer-ID.
**`data.images`** — Base64-kodierte erfasste Bilder:
FeldTypBeschreibung`data.images.document_image`stringBase64-kodiertes Bild der Dokumentvorderseite.`data.images.document_image_back`stringBase64-kodiertes Bild der Dokumentrückseite.`data.images.selfie`stringBase64-kodiertes Selfie-Bild, das bei der Verifizierung erfasst wurde.
**`data.response.unico`** — Konsolidiertes Urteil:
FeldTypBeschreibung`data.response.unico.process_id`string (UUID)Interner Bezeichner im Zusammenhang mit dem Verifizierungsprozess.`data.response.unico.result`stringProzessergebnis. Mögliche Werte sind unten beschrieben.
**Mögliche Werte für `data.response.unico.result`:**
Das Ergebnis kodiert eine von drei Bewertungsdimensionen:

**Identitätsbewertung** — ob das erfasste Gesicht zum Dokumenteninhaber gehört (`PROCESS_RESULT_VERIFIED`, `PROCESS_RESULT_NOT_APPROVED`).
**Betrugsverhalten** — ob Verhaltens- oder Netzwerksignale auf ein Betrugsrisiko hinweisen (`PROCESS_RESULT_LIVE`, `PROCESS_RESULT_HIGH_RISK`, `PROCESS_RESULT_CRITICAL_RISK`, `PROCESS_RESULT_NOT_APPROVED`).
**Liveness** — ob zum Aufnahmezeitpunkt ein echtes Gesicht erkannt wurde (`PROCESS_RESULT_NOT_LIVE`).

ErgebnisEmpfehlungBedeutungSignal`PROCESS_RESULT_ERROR`**Ablehnen**Prozess mit Fehler abgeschlossen.System`PROCESS_RESULT_VERIFIED`**Akzeptieren**Der Benutzer war zum Zeitpunkt der Aufnahme aktiv; es ist das Gesicht des Ausweisbesitzers und es wurden keine Betrugshinweise gefunden.Identität: bestätigt`PROCESS_RESULT_LIVE`**Überprüfen / Akzeptieren**Der Benutzer war zum Zeitpunkt der Aufnahme aktiv; es wurden keine ausreichenden Beweise gefunden, um zu garantieren, dass es sich um den Ausweisbesitzer handelt, und keine Betrugshinweise.Identität: nicht eindeutig · Betrug: keine`PROCESS_RESULT_HIGH_RISK`**Ablehnung empfehlen**Es wurde mindestens ein starker Betrugshinweis gefunden. Die endgültige Entscheidung liegt bei Ihnen.Betrugsverhalten: 1 starkes Signal`PROCESS_RESULT_CRITICAL_RISK`**Ablehnung empfehlen**Es wurden mindestens 2 starke Betrugshinweise gefunden. Die endgültige Entscheidung liegt bei Ihnen.Betrugsverhalten: 2+ starke Signale`PROCESS_RESULT_NOT_APPROVED`**Ablehnen**Ablehnung empfohlen, da mehrere Betrugsindizien erkannt wurden.Identität: abgelehnt · Betrugsverhalten: mehrere Signale`PROCESS_RESULT_NOT_LIVE`**Bis zu 2 Wiederholungsversuche erlauben**Der Benutzer war zum Zeitpunkt der Aufnahme nicht live, obwohl keine weiteren Betrugsindizien gefunden wurden.Liveness: Gesicht nicht live
Hinweis`PROCESS_RESULT_VERIFIED` **erfordert Aktivierung**. Standardmäßig ist dieses Ergebnis **nicht aktiv** — stimmen Sie sich mit Ihrem Unico-Projektmanager ab, wenn Sie es aktivieren möchten.
**Ergänzende Signale für Ihre Entscheidung:**
Für Fälle mit `LIVE`, `HIGH_RISK` oder `CRITICAL_RISK` ergänzen Sie Ihre Entscheidung mit diesen Feldern:
FeldTypBedeutung`face_match`booleanStatus des Gesichtsabgleichs zwischen Dokument und Selfie.`document.front.face_analysis.match_fraud_flag`booleanOb das Dokumentgesicht mit betrügerischer Aktivität in Verbindung gebracht wurde.`selfie.match_fraud_flag`booleanOb das Selfie-Gesicht mit betrügerischer Aktivität in Verbindung gebracht wurde.`warnings.external_id`stringWarnung, die darauf hinweist, dass das Gesicht des Benutzers mehreren externen IDs zugeordnet ist.
**`data.response`** — Signale auf oberster Ergebnisebene:
FeldTypBeschreibung`data.response.face_match`booleanOb das Selfie-Gesicht mit dem Dokumentgesicht übereinstimmt.`data.response.label`string (nullable)Reserviert für Ergebnisse aus bestimmten Teilprozessen; `null`, wenn nicht zutreffend.`data.response.reason`string (nullable)Gründe für das zugewiesene Label.`data.response.request_id`stringEindeutiger Bezeichner für die API-Anfrage.
**`data.response.curp`** — CURP-Validierung gegen RENAPO:
FeldTypBeschreibung`curp`stringDie analysierte CURP-Zeichenfolge.`government_valid`booleanOb die CURP gemäß RENAPO gültig ist.`government_name`stringVollständiger Name, der mit der CURP in der offiziellen Datenbank verknüpft ist.`name_to_CURP_valid`booleanOb der angegebene Name mit der CURP übereinstimmt.`is_mexican`booleanOb die CURP einem mexikanischen Staatsbürger entspricht.`deceased`booleanOb die CURP in der offiziellen Datenbank als verstorben markiert ist.`date_of_birth`stringGeburtsdatum, wie aus der CURP dekodiert (TT/MM/JJJJ).`age`integerBerechnetes Alter des Benutzers.`gender`stringGeschlecht, wie aus der CURP dekodiert (`M` oder `F`).`state_of_birth`stringGeburtsort, wie aus der CURP dekodiert.`state_iso`stringISO-3166-2-Code für den Geburtsort.
**`data.response.document.details`** — Dokumentenerkennung und Forensik:
FeldTypBeschreibung`detected`booleanOb ein Dokument im Bild erfolgreich erkannt wurde.`document_id`integerEindeutiger Bezeichner für das verarbeitete Dokument.`forensics.is_valid`stringForensisches Analyseergebnis: `yes`, `no` oder `inconclusive`.
**`data.response.document.front.information`** — OCR-extrahierte Felder von der INE-Vorderseite. Jedes Feld enthält `text` (extrahierter Wert) und `valid` (ob es strukturell validiert werden konnte):
FeldBeschreibung`name`Vorname(n).`last_name`Väterlicher Nachname.`mother_last_name`Mütterlicher Nachname.`complete_name`Vollständiger Name.`birthdate`Geburtsdatum (TT/MM/JJJJ).`sex`Geschlecht (`H` oder `M`).`curp`Aus dem Dokument extrahierte CURP.`electoral_key`Wahlschlüssel.`address`Adresse.`registration_year`Jahr der Dokumentenregistrierung.`valid_thru`Ablaufjahr des Dokuments.
**`data.response.document.front.face_analysis`** — Analyse des auf dem INE gefundenen Gesichts:
FeldTypBeschreibung`face_id`integerEindeutiger Bezeichner für diese Gesichtsinstanz.`face_id_v2`integerEindeutiger Bezeichner (Version 2).`unique_face_id_v2`integerDauerhafter Bezeichner für dieses physische Gesicht über alle Anfragen hinweg.`first_seen`stringZeitstempel des ersten Mal, dass dieses Gesicht im System gesehen wurde.`last_seen`stringZeitstempel des letzten Mal, dass dieses Gesicht im Netzwerk gesehen wurde.`last_seen_by_your_company`stringLetzter Zeitpunkt, zu dem dieses Gesicht in einer Anfrage Ihres Unternehmens gesehen wurde.`inquiry_date`stringZeitstempel der aktuellen Verifizierungsanfrage.`match`booleanOb dieses Gesicht eine potenzielle Übereinstimmung mit anderen Gesichtern in der Datenbank ist.`match_fraud_flag`booleanOb dieses Gesicht mit betrügerischer Aktivität in Verbindung gebracht wurde.`seen_by_your_company`booleanOb dieses Gesicht zuvor von Ihrem Unternehmen gesehen wurde.`seen_different_companies`integerAnzahl anderer Unternehmen im Netzwerk, die dieses Gesicht gesehen haben.`times_seen_by_your_company`integerGesamtanzahl, wie oft dieses Gesicht in Anfragen Ihres Unternehmens gesehen wurde.`times_seen_last_month`integerAnzahl der Sichtungen im letzten Monat im gesamten Netzwerk.`warnings.external_id`stringWarnung, wenn das Gesicht des Benutzers mehreren externen IDs zugeordnet ist.
**`data.response.document.back`** — MRZ-Daten von der INE-Rückseite:
FeldTypBeschreibung`mrz`stringVollständige MRZ-Zeichenfolge (maschinenlesbare Zone).`cic`stringCIC-Nummer, aus der MRZ extrahiert.`citizen_id`stringBürger-Identifikationsnummer aus der MRZ.
**`data.response.selfie`** — Analyse des erfassten Selfies:
FeldTypBeschreibung`face_id`integerEindeutiger Bezeichner für die Selfie-Gesichtsinstanz.`face_id_v2`integerEindeutiger Bezeichner (Version 2).`unique_face_id_v2`integerDauerhafter Bezeichner für dieses physische Gesicht über alle Anfragen hinweg.`first_seen`stringErstes Mal, dass das Gesicht dieses Selfies im System gesehen wurde.`first_seen_image`booleanOb dieses genaue Bild zum ersten Mal gesehen wurde.`last_seen`stringLetzter Zeitpunkt, zu dem dieses Gesicht im Netzwerk gesehen wurde.`last_seen_by_your_company`stringLetzter Zeitpunkt, zu dem dieses Gesicht von Ihrem Unternehmen gesehen wurde.`inquiry_date`stringZeitstempel der aktuellen Verifizierungsanfrage.`match`booleanOb das Selfie-Gesicht mit anderen Gesichtern in der Datenbank übereinstimmt.`match_fraud_flag`booleanOb das Selfie-Gesicht mit betrügerischer Aktivität in Verbindung gebracht wurde.`seen_by_your_company`booleanOb dieses Gesicht zuvor von Ihrem Unternehmen gesehen wurde.`seen_different_companies`integerAnzahl anderer Unternehmen im Netzwerk, die dieses Gesicht gesehen haben.`times_seen_by_your_company`integerGesamtanzahl, wie oft dieses Gesicht in Anfragen Ihres Unternehmens gesehen wurde.`times_seen_last_month`integerAnzahl der Sichtungen im letzten Monat im gesamten Netzwerk.`warnings`objectSpezifische Warnungen bezüglich der Selfie-Analyse (gleiche Struktur wie document face_analysis).
Verwenden Sie Polling mit **exponentiellem Backoff** — rufen Sie nicht in einer engen Schleife auf.
**Fehlerantworten — GET /v2/history/request**CodeMeldungBeschreibung`400 Bad Request``Input should be a valid UUID, invalid group length...`Der Parameter `magic_link_token` ist fehlerhaft oder kein gültiges UUID-Format.`404 Not Found``This magic link have no requests associated`Das angegebene Token existiert, hat aber keine abgeschlossenen KYC-Prozesse verknüpft. Der Benutzer hat die Journey möglicherweise noch nicht abgeschlossen.`500 Internal Server Error``internal server error`Serverseitiger Verarbeitungsfehler. Wiederholen Sie den Vorgang mit exponentiellem Backoff. Bei Persistenz wenden Sie sich an den Support.**Beispiel 400-Antwort:**```
{  "data": {    "error": [      {        "attribute": ["magic_link_token"],        "message": "Input should be a valid UUID, invalid group length in group 4: expected 12, found 11",        "type": "uuid_parsing"      }    ]  },  "request_date": "2025-07-28T20:43:34",  "status": "There are some errors in the request",  "status_code": 400,  "version": "v3.6.0"}
```

**Beispiel 404-Antwort:**```
{  "data": {    "error": "This magic link have no requests associated"  },  "request_date": "2025-07-28T20:40:50",  "status": "Nothing matches the given URI",  "status_code": 404,  "version": "v3.6.0"}
```

**Beispiel 500-Antwort:**```
{  "data": {    "error": "internal server error"  },  "version": "v1.4.2",  "status": "bad request",  "status_code": 400,  "request_date": "2025-07-28T20:22:29+0000",  "request": {    "metadata": null  }}
```

### Webhook V2​

Es stehen drei Webhook-Ereignisse zur Verfügung. Zur Aktivierung wenden Sie sich an Ihren Onboarding-Projektmanager mit: Endpunkt-**URL** (HTTPS erforderlich), **Authentifizierungstyp** (`basic_auth`, `api_key`, `oauth2` oder `NoAuth`), **Authentifizierungskonfiguration**, **maximale Wiederholungsversuche**, **Wiederholungsintervall (s)** und **Timeout (s)**.
MAGIC_LINK_RESULTS
Dieses Ereignis wird am Ende des Ablaufs gesendet, wenn der Decision Maker die Verarbeitung der gesendeten Informationen abgeschlossen hat.
```
{  "data": {    "images": {      "document_image": "base64str",      "document_image_back": "base64str",      "selfie": "base64str"    },    "response": {      "document": {        "details": {          "detected": true,          "forensics": {            "is_valid": "yes"          },          "document_id": 123        },        "front": {          "information": {            "birthdate": { "text": "14/11/1956", "valid": true },            "sex": { "text": "H", "valid": true },            "registration_year": { "text": "1998", "valid": true },            "name": { "text": "LUKE", "valid": true },            "mother_last_name": { "text": "ORGANA", "valid": true },            "last_name": { "text": "SKYWALKER", "valid": true },            "electoral_key": { "text": "GRCRSN82031007M500", "valid": true },            "curp": { "text": "GOCJ850627HDFRRL09", "valid": true },            "address": { "text": "DOMICILIO/ADDRESS, HARLINGEN, TX 78552", "valid": false },            "complete_name": { "text": "LUKE SKYWALKER", "valid": true },            "valid_thru": { "text": "2027", "valid": true }          },          "face_analysis": {            "face_id": 237437,            "first_seen": "12/22/2022, 18:54:09",            "unique_face_id_v2": 126880,            "face_id_v2": 199068,            "inquiry_date": "07/28/2025, 20:53:12",            "last_seen": "07/28/2025, 18:47:46",            "last_seen_by_your_company": "07/24/2025, 21:38:21",            "match": true,            "match_fraud_flag": true,            "seen_by_your_company": true,            "seen_different_companies": 46,            "times_seen_by_your_company": 3,            "times_seen_last_month": 111,            "warnings": {              "external_id": "User found in the company with other external_ids: ['abc-123']"            }          }        },        "back": {          "mrz": "IDMEX999999999999<9 VADER<SKYWALKER<<LUKE",          "cic": "237457894"        }      },      "selfie": {        "face_id": 237436,        "first_seen": "02/05/2025, 02:36:19",        "unique_face_id_v2": 494,        "face_id_v2": 4378,        "inquiry_date": "07/28/2025, 20:52:49",        "last_seen": "07/28/2025, 20:52:51",        "last_seen_by_your_company": "07/23/2025, 18:14:27",        "match": true,        "match_fraud_flag": true,        "seen_by_your_company": true,        "seen_different_companies": 2,        "times_seen_by_your_company": 2,        "times_seen_last_month": 7,        "warnings": {          "external_id": "User found in the company with other external_ids: ['abc-123']"        },        "first_seen_image": true      },      "face_match": false,      "curp": {        "curp": "GOCJ850627HDFRRL09",        "state_of_birth": "Nuevo León",        "state_iso": "MX-NLE",        "date_of_birth": "14/11/1956",        "age": 58,        "gender": "M",        "is_mexican": true,        "name_to_CURP_valid": true,        "government_valid": true,        "government_name": "LUKE SKYWALKER",        "deceased": false      },      "unico": {        "process_id": "d333dfac-9ddb-4066-8e2c-44eaf4c86b4a",        "result": "PROCESS_RESULT_LIVE"      },      "label": null,      "reason": null,      "request_id": "d1kxp9ah8f0s71uv9zx0"    },    "user_id": null  },  "event": "MAGIC_LINK_RESULTS",  "magic_link_token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",  "user_id": null,  "date": "2025-10-03T21:15:41.299815"}
```

MAGIC_LINK_TRACK
Diese Ereignisse werden empfangen, wenn der Benutzer eine Aktion abgeschlossen hat. Zum Beispiel wird `form_start` empfangen, wenn der Benutzer gerade die Vorderseite des Dokuments aufnimmt, was bedeutet, dass der Benutzer auf den ersten Bildschirm geklickt und ihn abgeschlossen hat.
```
{  "data": {    "completed_on": "Fri, 03 Oct 2025 21:15:35 GMT",    "started_on": "Fri, 03 Oct 2025 21:15:30 GMT",    "step": "form_start",    "user_id": null  },  "event": "MAGIC_LINK_TRACK",  "magic_link_token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",  "user_id": null,  "date": "2025-10-03T21:15:41.299815"}
```

FeldTypBeschreibung`data.step`stringName des abgeschlossenen Schritts.`data.user_id`string (nullable)Externe ID, die im Magic Link festgelegt ist.`data.started_on`datetimeStartzeit des Schritts in UTC.`data.completed_on`datetimeAbschlusszeit des Schritts in UTC.`event`stringEreignistyp-Bezeichner.`magic_link_token`uuidEindeutiges Magic-Link-Token.`user_id`string (nullable)Externer Bezeichner.`date`datetimeEreigniszeitstempel.
**Unterstützte Schritte:**
SchrittBeschreibung`form_start`Benutzer hat den ersten Magic-Link-Button geklickt.`form_document_front`Benutzer hat die INE-Vorderseite erfasst.`form_document_back`Benutzer hat die INE-Rückseite erfasst.`form_document`Benutzer hat Vorder- und Rückseite abgeschlossen.`form_selfie`Benutzer hat den Liveness-Prozess abgeschlossen.`form_decision_maker`Benutzer hat den gesamten Ablauf abgeschlossen.
MAGIC_LINK_DOCUMENT_RETAKE_REASONS
Dieses Ereignis wird gesendet, wenn eine erneute Dokumentenaufnahme erforderlich ist, entweder während des Vorder- oder Rückseitenprozesses. Es zeigt an, dass kritische Daten des INE nicht gelesen werden konnten.
```
{  "data": {    "document_type": "ine_front",    "invalid_back_ocr": false,    "invalid_curp": false,    "invalid_document": true  },  "event": "MAGIC_LINK_DOCUMENT_RETAKE_REASONS",  "magic_link_token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530",  "user_id": null,  "date": "2025-10-03T21:12:00.000Z"}
```

FeldTypBeschreibung`data.document_type`stringDokumentseite: `ine_front` oder `ine_back`.`data.invalid_document`boolean`true`, wenn das erfasste Bild kein gültiges INE ist (jede Seite).`data.invalid_curp`boolean`true`, wenn die CURP nicht gelesen werden konnte (nur `ine_front`).`data.invalid_back_ocr`boolean`true`, wenn der MRZ-Code nicht gelesen werden konnte (nur `ine_back`).`event`stringEreignistyp-Bezeichner.`magic_link_token`uuidEindeutiges Magic-Link-Token.`user_id`string (nullable)Externer Bezeichner.`date`datetimeEreigniszeitstempel.
Der Payload ist so gestaltet, dass für jede Dokumentseite nur **ein** Fehler (`true`) empfangen wird.
**Fehlerszenarien — INE-Vorderseite:**

Ungültiges Dokument → nur `invalid_document: true`
CURP-Lesefehler → nur `invalid_curp: true`

**Fehlerszenarien — INE-Rückseite:**

Ungültiges Dokument → nur `invalid_document: true`
MRZ-Lesefehler → nur `invalid_back_ocr: true`

V1 / V2-KompatibilitätWenn Sie weiterhin `webhook_url` in den `metadata` der Anfrage senden (Webhook V1), hat diese Konfiguration **Vorrang** vor dem globalen V2. Zur Migration entfernen Sie `webhook_url` aus `metadata` und konfigurieren Sie V2 mit Ihrem Onboarding-PM.

### Anpassungen​

Die gehostete Magic-Link-Seite **unterstützt keine visuelle Anpassung** durch den Kunden — sie folgt der Standard-Unico/Trully-Identität. Um die Journey anzupassen (Logo, Farben, Texte), verwenden Sie Onboarding (Global) mit SDK oder Web.
**Verfügbarkeit:** Mexiko · **Endpunkt:** `POST https://api.trully.ai/v2/magic-link` · **Dokument:** INE · **Authentifizierung:** `x-api-key` (Trully)Zuletzt aktualisiert am 8. Okt. 2026**