Zum Hauptinhalt springen

KYC Magic Link

Separater regionaler Vertrag

Dieser Anwendungsfall verwendet nicht den Unico-Endpunkt POST /v1/process und auch nicht den API/TCA-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)LivenessRisk Fraud ClassificationIdentity Verification
CapabilityErforderlichRolle im Ablauf
Document CaptureErforderlichErfasst das INE-Dokumentenbild. Die Wiederverwendung von Dokumenten ist in diesem Anwendungsfall nicht verfügbar — jede Sitzung erfordert eine neue Erfassung.
LivenessErforderlichLiveness-Prüfung — obligatorisches Selfie, das den Prozess verankert.
Risk Fraud ClassificationErforderlichGleicht Verhaltenssignale ab, um das mit der CPF verbundene Betrugsrisiko zu kennzeichnen.
Identity VerificationOptional (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.

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-keyJaAPI-Schlüssel, bereitgestellt von Ihrem Onboarding-Projektmanager bei Unico.
Content-TypeJaapplication/json

Body (application/json):

FeldTypErforderlichBeschreibung
external_idstringNeinEin externer Bezeichner für die Anfrage, der für Tracking- und Referenzzwecke verwendet wird.
metadataobjectNeinContainer für Konfigurationsparameter.
metadata.phonestringNeinTelefonnummer des Benutzers im internationalen Format (z. B. 521234567890).
metadata.redirect_urlstringNeinURL, zu der der Benutzer nach Abschluss des KYC-Prozesses weitergeleitet wird.
metadata.webhook_urlstringNeinURL, 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_urlstringNeinURL, 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.

Mögliche Werte für data.step (gesendet an track_webhook_url):

SchrittBeschreibung
form_startDer Benutzer scannt gerade das Dokument.
form_document_frontDer Benutzer hat bereits die INE-Vorderseite erfasst.
form_document_backDer Benutzer hat bereits die INE-Rückseite erfasst.
form_documentDer Prozess befindet sich gerade im Selfie-Schritt.
form_selfieDer Benutzer hat den letzten Schritt des Vorgangs erreicht.
form_decision_makerDer Vorgang gibt die Systemantwort zurück.

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_idstring (nullable)Ein externer Bezeichner für die Anfrage, der für Tracking- und Referenzzwecke verwendet wird.
data.created_onstring (date-time)Das Datum, an dem der Magic Link erstellt wurde.
data.is_activebooleanWenn true, ist der Magic Link aktiv.
data.tokenstringDas Token des Magic Links, das verwendet wird, um die KYC-Prozesse mit dem Magic Link zu verknüpfen.
data.magic_link_urlstring (URI)Die Magic-URL, um den KYC-Prozess zu starten.
data.metadata.redirect_urlstring (nullable)URL, zu der der Benutzer nach Abschluss des KYC-Prozesses weitergeleitet wird.
data.metadata.webhook_urlstring (nullable)URL, an die die KYC-Prozessdaten nach Abschluss gesendet werden. Dieser Webhook wird auf der Client-Seite aufgerufen.
data.metadata.track_webhook_urlstring (nullable)URL, an die jeder vom Benutzer verarbeitete KYC-Schritt gesendet wird. Dieser Webhook wird auf der Client-Seite aufgerufen.
data.versionstringDie Version des Magic Links.
versionstringDie Version der API, die die Anfrage verarbeitet hat, nützlich zur Verfolgung von Änderungen und Kompatibilität.
statusstringEine textuelle Darstellung des Antwortstatus, die den Erfolg oder Misserfolg des Vorgangs anzeigt.
status_codeintegerDer HTTP-Statuscode der Antwort, der einen standardisierten Indikator für das Ergebnis der Anfrage liefert.
request_datestring (date-time)Datum und Uhrzeit der Anfrage im ISO-8601-Format.
request.metadata.redirect_urlstring (nullable)URL, zu der der Benutzer nach Abschluss des KYC-Prozesses weitergeleitet wird (Echo der Anfrage).
request.metadata.webhook_urlstring (nullable)URL, an die die KYC-Prozessdaten nach Abschluss gesendet werden (Echo der Anfrage).
request.metadata.track_webhook_urlstring (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 Requestdata provided in the field is invalidUngültige Datenstruktur oder Feldwerte in der Anfrage-Payload. Überprüfen Sie Pflichtfelder und Formate.
403 ForbiddenForbiddenAPI-Schlüssel fehlt, ist abgelaufen oder hat keine Berechtigung. Überprüfen Sie den Header x-api-key.
500 Internal Server Errorinternal server errorServerseitiger 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.

4. Ergebnis empfangen
  • Polling via GET (erforderlich) — rufen Sie GET /v2/history/request?magic_link_token={token} periodisch auf, bis unico.result befüllt ist. Siehe Polling via GET unten.
  • Webhook (optional) — konfigurieren Sie mit Ihrem Onboarding-PM, um Ereignisse automatisch zu empfangen. Siehe Webhook unten.

Polling via GET​

Endpunkt: GET https://sandbox.trully.ai/v2/history/request

Abfrageparameter:

ParameterTypErforderlichBeschreibung
magic_link_tokenstringJaToken, das bei der Erstellung des Magic Links zurückgegeben wurde.

Header:

HeaderErforderlichBeschreibung
x-api-keyJaAPI-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
statusstringTextuelle Darstellung des Antwortstatus.
status_codeintegerHTTP-Statuscode.
request_datestring (date-time)Datum und Uhrzeit der Anfrage.
versionstringAPI-Version, die die Anfrage verarbeitet hat.
data.user_idstringDie in der ursprünglichen Anfrage festgelegte Benutzer-ID.

data.images — Base64-kodierte erfasste Bilder:

FeldTypBeschreibung
data.images.document_imagestringBase64-kodiertes Bild der Dokumentvorderseite.
data.images.document_image_backstringBase64-kodiertes Bild der Dokumentrückseite.
data.images.selfiestringBase64-kodiertes Selfie-Bild, das bei der Verifizierung erfasst wurde.

data.response.unico — Konsolidiertes Urteil:

FeldTypBeschreibung
data.response.unico.process_idstring (UUID)Interner Bezeichner im Zusammenhang mit dem Verifizierungsprozess.
data.response.unico.resultstringProzessergebnis. 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_ERRORAblehnenProzess mit Fehler abgeschlossen.System
PROCESS_RESULT_VERIFIEDAkzeptierenDer 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 / AkzeptierenDer 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_RISKAblehnung empfehlenEs wurde mindestens ein starker Betrugshinweis gefunden. Die endgültige Entscheidung liegt bei Ihnen.Betrugsverhalten: 1 starkes Signal
PROCESS_RESULT_CRITICAL_RISKAblehnung empfehlenEs wurden mindestens 2 starke Betrugshinweise gefunden. Die endgültige Entscheidung liegt bei Ihnen.Betrugsverhalten: 2+ starke Signale
PROCESS_RESULT_NOT_APPROVEDAblehnenAblehnung empfohlen, da mehrere Betrugsindizien erkannt wurden.Identität: abgelehnt · Betrugsverhalten: mehrere Signale
PROCESS_RESULT_NOT_LIVEBis zu 2 Wiederholungsversuche erlaubenDer 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_matchbooleanStatus des Gesichtsabgleichs zwischen Dokument und Selfie.
document.front.face_analysis.match_fraud_flagbooleanOb das Dokumentgesicht mit betrügerischer Aktivität in Verbindung gebracht wurde.
selfie.match_fraud_flagbooleanOb das Selfie-Gesicht mit betrügerischer Aktivität in Verbindung gebracht wurde.
warnings.external_idstringWarnung, die darauf hinweist, dass das Gesicht des Benutzers mehreren externen IDs zugeordnet ist.

data.response — Signale auf oberster Ergebnisebene:

FeldTypBeschreibung
data.response.face_matchbooleanOb das Selfie-Gesicht mit dem Dokumentgesicht übereinstimmt.
data.response.labelstring (nullable)Reserviert für Ergebnisse aus bestimmten Teilprozessen; null, wenn nicht zutreffend.
data.response.reasonstring (nullable)Gründe für das zugewiesene Label.
data.response.request_idstringEindeutiger Bezeichner für die API-Anfrage.

data.response.curp — CURP-Validierung gegen RENAPO:

FeldTypBeschreibung
curpstringDie analysierte CURP-Zeichenfolge.
government_validbooleanOb die CURP gemäß RENAPO gültig ist.
government_namestringVollständiger Name, der mit der CURP in der offiziellen Datenbank verknüpft ist.
name_to_CURP_validbooleanOb der angegebene Name mit der CURP übereinstimmt.
is_mexicanbooleanOb die CURP einem mexikanischen Staatsbürger entspricht.
deceasedbooleanOb die CURP in der offiziellen Datenbank als verstorben markiert ist.
date_of_birthstringGeburtsdatum, wie aus der CURP dekodiert (TT/MM/JJJJ).
ageintegerBerechnetes Alter des Benutzers.
genderstringGeschlecht, wie aus der CURP dekodiert (M oder F).
state_of_birthstringGeburtsort, wie aus der CURP dekodiert.
state_isostringISO-3166-2-Code für den Geburtsort.

data.response.document.details — Dokumentenerkennung und Forensik:

FeldTypBeschreibung
detectedbooleanOb ein Dokument im Bild erfolgreich erkannt wurde.
document_idintegerEindeutiger Bezeichner für das verarbeitete Dokument.
forensics.is_validstringForensisches 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
nameVorname(n).
last_nameVäterlicher Nachname.
mother_last_nameMütterlicher Nachname.
complete_nameVollständiger Name.
birthdateGeburtsdatum (TT/MM/JJJJ).
sexGeschlecht (H oder M).
curpAus dem Dokument extrahierte CURP.
electoral_keyWahlschlüssel.
addressAdresse.
registration_yearJahr der Dokumentenregistrierung.
valid_thruAblaufjahr des Dokuments.

data.response.document.front.face_analysis — Analyse des auf dem INE gefundenen Gesichts:

FeldTypBeschreibung
face_idintegerEindeutiger Bezeichner für diese Gesichtsinstanz.
face_id_v2integerEindeutiger Bezeichner (Version 2).
unique_face_id_v2integerDauerhafter Bezeichner für dieses physische Gesicht über alle Anfragen hinweg.
first_seenstringZeitstempel des ersten Mal, dass dieses Gesicht im System gesehen wurde.
last_seenstringZeitstempel des letzten Mal, dass dieses Gesicht im Netzwerk gesehen wurde.
last_seen_by_your_companystringLetzter Zeitpunkt, zu dem dieses Gesicht in einer Anfrage Ihres Unternehmens gesehen wurde.
inquiry_datestringZeitstempel der aktuellen Verifizierungsanfrage.
matchbooleanOb dieses Gesicht eine potenzielle Übereinstimmung mit anderen Gesichtern in der Datenbank ist.
match_fraud_flagbooleanOb dieses Gesicht mit betrügerischer Aktivität in Verbindung gebracht wurde.
seen_by_your_companybooleanOb dieses Gesicht zuvor von Ihrem Unternehmen gesehen wurde.
seen_different_companiesintegerAnzahl anderer Unternehmen im Netzwerk, die dieses Gesicht gesehen haben.
times_seen_by_your_companyintegerGesamtanzahl, wie oft dieses Gesicht in Anfragen Ihres Unternehmens gesehen wurde.
times_seen_last_monthintegerAnzahl der Sichtungen im letzten Monat im gesamten Netzwerk.
warnings.external_idstringWarnung, wenn das Gesicht des Benutzers mehreren externen IDs zugeordnet ist.

data.response.document.back — MRZ-Daten von der INE-Rückseite:

FeldTypBeschreibung
mrzstringVollständige MRZ-Zeichenfolge (maschinenlesbare Zone).
cicstringCIC-Nummer, aus der MRZ extrahiert.
citizen_idstringBürger-Identifikationsnummer aus der MRZ.

data.response.selfie — Analyse des erfassten Selfies:

FeldTypBeschreibung
face_idintegerEindeutiger Bezeichner für die Selfie-Gesichtsinstanz.
face_id_v2integerEindeutiger Bezeichner (Version 2).
unique_face_id_v2integerDauerhafter Bezeichner für dieses physische Gesicht über alle Anfragen hinweg.
first_seenstringErstes Mal, dass das Gesicht dieses Selfies im System gesehen wurde.
first_seen_imagebooleanOb dieses genaue Bild zum ersten Mal gesehen wurde.
last_seenstringLetzter Zeitpunkt, zu dem dieses Gesicht im Netzwerk gesehen wurde.
last_seen_by_your_companystringLetzter Zeitpunkt, zu dem dieses Gesicht von Ihrem Unternehmen gesehen wurde.
inquiry_datestringZeitstempel der aktuellen Verifizierungsanfrage.
matchbooleanOb das Selfie-Gesicht mit anderen Gesichtern in der Datenbank übereinstimmt.
match_fraud_flagbooleanOb das Selfie-Gesicht mit betrügerischer Aktivität in Verbindung gebracht wurde.
seen_by_your_companybooleanOb dieses Gesicht zuvor von Ihrem Unternehmen gesehen wurde.
seen_different_companiesintegerAnzahl anderer Unternehmen im Netzwerk, die dieses Gesicht gesehen haben.
times_seen_by_your_companyintegerGesamtanzahl, wie oft dieses Gesicht in Anfragen Ihres Unternehmens gesehen wurde.
times_seen_last_monthintegerAnzahl der Sichtungen im letzten Monat im gesamten Netzwerk.
warningsobjectSpezifische 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 RequestInput should be a valid UUID, invalid group length...Der Parameter magic_link_token ist fehlerhaft oder kein gültiges UUID-Format.
404 Not FoundThis magic link have no requests associatedDas angegebene Token existiert, hat aber keine abgeschlossenen KYC-Prozesse verknüpft. Der Benutzer hat die Journey möglicherweise noch nicht abgeschlossen.
500 Internal Server Errorinternal server errorServerseitiger 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​

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.stepstringName des abgeschlossenen Schritts.
data.user_idstring (nullable)Externe ID, die im Magic Link festgelegt ist.
data.started_ondatetimeStartzeit des Schritts in UTC.
data.completed_ondatetimeAbschlusszeit des Schritts in UTC.
eventstringEreignistyp-Bezeichner.
magic_link_tokenuuidEindeutiges Magic-Link-Token.
user_idstring (nullable)Externer Bezeichner.
datedatetimeEreigniszeitstempel.

Unterstützte Schritte:

SchrittBeschreibung
form_startBenutzer hat den ersten Magic-Link-Button geklickt.
form_document_frontBenutzer hat die INE-Vorderseite erfasst.
form_document_backBenutzer hat die INE-Rückseite erfasst.
form_documentBenutzer hat Vorder- und Rückseite abgeschlossen.
form_selfieBenutzer hat den Liveness-Prozess abgeschlossen.
form_decision_makerBenutzer 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_typestringDokumentseite: ine_front oder ine_back.
data.invalid_documentbooleantrue, wenn das erfasste Bild kein gültiges INE ist (jede Seite).
data.invalid_curpbooleantrue, wenn die CURP nicht gelesen werden konnte (nur ine_front).
data.invalid_back_ocrbooleantrue, wenn der MRZ-Code nicht gelesen werden konnte (nur ine_back).
eventstringEreignistyp-Bezeichner.
magic_link_tokenuuidEindeutiges Magic-Link-Token.
user_idstring (nullable)Externer Bezeichner.
datedatetimeEreigniszeitstempel.

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ät

Wenn 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