KYC Magic Link

अलग क्षेत्रीय अनुबंध

यह उपयोग मामला POST /v1/process Unico endpoint या API अनुबंध का उपयोग नहीं करता। एकीकरण Trully.ai (host api.trully.ai) के साथ है, Bearer JWT के बजाय x-api-key के माध्यम से प्रमाणीकरण के साथ, और एक स्वामित्व प्रतिक्रिया स्कीमा के साथ। अन्य देशों के लिए, Onboarding (Global) का उपयोग करें।

यह उपयोग मामला क्या हल करता है

KYC Magic Link मेक्सिको में पहचान प्रक्रिया को निष्पादित करने, राष्ट्रीय पहचान दस्तावेज़ (INE) और चेहरे की बायोमेट्रिक्स एकत्र करने की चुनौती को संबोधित करता है। Unico द्वारा होस्ट की गई यात्रा के साथ, आप अपने स्वयं के चैनलों (WhatsApp, SMS, ईमेल) के माध्यम से भेजे गए एक लिंक के माध्यम से फ्रंट-एंड विकास की बाधा को समाप्त कर देते हैं।

इस उपयोग मामले का उपयोग करें जब:

आप मेक्सिको में काम करते हैं और उपयोग किया जाने वाला पहचान दस्तावेज़ INE (अनिवार्य) है।

इस उपयोग मामले का उपयोग न करें जब:

उपयोगकर्ता मेक्सिको के बाहर है या अन्य दस्तावेजों का उपयोग करता है → अन्य onboarding उपयोग मामलों को देखें।

शामिल क्षमताएं

एक ही प्रक्रिया में निष्पादित pipeline:

दस्तावेज़ कैप्चर (INE)

Liveness

जोखिम वर्गीकरण

पहचान सत्यापन

क्षमता	आवश्यक	प्रवाह में भूमिका
दस्तावेज़ कैप्चर	आवश्यक	INE दस्तावेज़ की छवि कैप्चर करता है। इस उपयोग मामले में दस्तावेज़ पुनः उपयोग उपलब्ध नहीं है — प्रत्येक सत्र के लिए एक नई कैप्चर आवश्यक है।
Liveness	आवश्यक	Liveness जांच — अनिवार्य सेल्फी जो प्रक्रिया को आधार देती है।
जोखिम वर्गीकरण	आवश्यक	CPF से जुड़े धोखाधड़ी के जोखिम को चिह्नित करने के लिए व्यवहार संबंधी संकेतों का क्रॉस-रेफरेंस करता है।
पहचान सत्यापन	वैकल्पिक (यदि अनुबंधित)	Unico की पहचान आधार और अतिरिक्त संकेतों का उपयोग करके सत्यापित करता है कि लेनदेन का चेहरा प्रदान किए गए सरकारी पहचानकर्ता के धारक का है या नहीं।
RENAPO Verification	वैकल्पिक (यदि अनुबंधित)	उपयोगकर्ता के CURP के साथ मेक्सिको की राष्ट्रीय जनसंख्या रजिस्ट्री RENAPO से query करता है और पहचान सत्यापन परिणाम के साथ रजिस्ट्री रिकॉर्ड लौटाता है।

पूर्वापेक्षाएं

API key — Unico में आपके Onboarding Project Manager द्वारा प्रावधानित। x-api-key header में भेजा गया।
Public HTTPS endpoint — webhooks प्राप्त करने के लिए (वैकल्पिक, लेकिन अनुशंसित)।
CORS कॉन्फ़िगरेशन — webhook प्राप्त करने वाले सर्वर पर origins https://verification.unico.app (production) और https://verification.uat.unico.app (sandbox) को अनुमति दें।

चरण-दर-चरण कार्यान्वयन

अन्य उपयोग मामलों के विपरीत, Magic Link में flow field नहीं है — एकीकरण सीधे Trully API के साथ है। endpoint एक अद्वितीय सत्यापन लिंक बनाता है जिसे आप अपने स्वयं के चैनल के माध्यम से उपयोगकर्ता को वितरित करते हैं।

1. Magic Link बनाएं

Endpoint: POST https://sandbox.trully.ai/v2/magic-link

Headers:

Header	आवश्यक	विवरण
`x-api-key`	हां	Unico में आपके Onboarding Project Manager द्वारा प्रावधानित API key।
`Content-Type`	हां	`application/json`

Body (application/json):

Field	Type	आवश्यक	विवरण
`external_id`	string	नहीं	अनुरोध के लिए एक बाहरी पहचानकर्ता, ट्रैकिंग और संदर्भ उद्देश्यों के लिए उपयोग किया जाता है।
`metadata`	object	नहीं	कॉन्फ़िगरेशन पैरामीटर के लिए कंटेनर।
`metadata.phone`	string	नहीं	अंतर्राष्ट्रीय प्रारूप में उपयोगकर्ता का फ़ोन नंबर (जैसे, `521234567890`)।
`metadata.redirect_url`	string	नहीं	KYC प्रक्रिया पूरी होने के बाद उपयोगकर्ता को redirect करने का URL।
`metadata.webhook_url`	string	नहीं	KYC प्रक्रिया पूरी होने के बाद KYC प्रक्रिया डेटा भेजने का URL। यह webhook client side में call किया जाएगा। सुरक्षा कारणों से endpoint को HTTPS का उपयोग करना चाहिए। component आपके webhook server के जवाब देने के लिए एक मिनट प्रतीक्षा करेगा — उसके बाद, यह संचार बंद कर देगा। प्रक्रिया किसी भी तरह से webhook संचार से प्रभावित नहीं होगी। सुनिश्चित करें कि production और sandbox के लिए क्रमशः `https://verification.unico.app` और `https://verification.uat.unico.app` को अपने CORS कॉन्फ़िगरेशन में अनुमति दें।
`metadata.track_webhook_url`	string	नहीं	उपयोगकर्ता द्वारा संसाधित प्रत्येक KYC चरण भेजने का URL (नीचे webhook events देखें)। यह webhook client side में call किया जाएगा। सुरक्षा कारणों से endpoint को HTTPS का उपयोग करना चाहिए। component आपके webhook server के जवाब देने के लिए एक मिनट प्रतीक्षा करेगा — उसके बाद, यह संचार बंद कर देगा। प्रक्रिया किसी भी तरह से webhook संचार से प्रभावित नहीं होगी। सुनिश्चित करें कि production और sandbox के लिए क्रमशः `https://verification.unico.app` और `https://verification.uat.unico.app` को अपने CORS कॉन्फ़िगरेशन में अनुमति दें।

data.step (जो track_webhook_url को भेजा जाता है) वही चरण रिपोर्ट करता है जो Webhook V2 द्वारा ट्रैक किए जाते हैं — नीचे समर्थित चरण तालिका देखें।

उदाहरण अनुरोध:

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. टोकन और लिंक URL प्राप्त करें

प्रतिक्रिया fields:

Field	Type	विवरण
`data.external_id`	string (nullable)	अनुरोध के लिए एक बाहरी पहचानकर्ता, ट्रैकिंग और संदर्भ उद्देश्यों के लिए उपयोग किया जाता है।
`data.created_on`	string (date-time)	magic link बनाए जाने की तारीख।
`data.is_active`	boolean	यदि `true`, तो magic link सक्रिय है।
`data.token`	string	magic link का टोकन जो KYC प्रक्रियाओं को magic link से जोड़ने के लिए उपयोग किया जाएगा।
`data.magic_link_url`	string (URI)	KYC प्रक्रिया शुरू करने के लिए magic URL लिंक।
`data.metadata.redirect_url`	string (nullable)	KYC प्रक्रिया पूरी होने के बाद उपयोगकर्ता को redirect करने का URL।
`data.metadata.webhook_url`	string (nullable)	KYC प्रक्रिया पूरी होने के बाद KYC प्रक्रिया डेटा भेजने का URL। यह webhook client side में call किया जाएगा।
`data.metadata.track_webhook_url`	string (nullable)	उपयोगकर्ता द्वारा संसाधित प्रत्येक KYC चरण भेजने का URL। यह webhook client side में call किया जाएगा।
`data.version`	string	magic link का संस्करण।
`version`	string	API का संस्करण जिसने अनुरोध संसाधित किया, परिवर्तनों और संगतता को ट्रैक करने के लिए उपयोगी।
`status`	string	प्रतिक्रिया स्थिति का पाठ्य प्रतिनिधित्व, ऑपरेशन की सफलता या विफलता को दर्शाता है।
`status_code`	integer	प्रतिक्रिया का HTTP status code, अनुरोध के परिणाम का एक मानकीकृत संकेतक प्रदान करता है।
`request_date`	string (date-time)	अनुरोध किए जाने की तारीख और समय, ISO 8601 प्रारूप में।
`request.metadata.redirect_url`	string (nullable)	KYC प्रक्रिया पूरी होने के बाद उपयोगकर्ता को redirect करने का URL (अनुरोध की प्रतिध्वनि)।
`request.metadata.webhook_url`	string (nullable)	पूरा होने के बाद KYC प्रक्रिया डेटा भेजने का URL (अनुरोध की प्रतिध्वनि)।
`request.metadata.track_webhook_url`	string (nullable)	उपयोगकर्ता द्वारा संसाधित प्रत्येक KYC चरण भेजने का URL (अनुरोध की प्रतिध्वनि)।

उदाहरण प्रतिक्रिया:

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

त्रुटि प्रतिक्रियाएं — POST /v2/magic-link

Code	Message	विवरण
`400 Bad Request`	`data provided in the field is invalid`	अनुरोध payload में अमान्य डेटा संरचना या field मान। आवश्यक fields और प्रारूपों की जांच करें।
`403 Forbidden`	`Forbidden`	API key गायब है, समाप्त हो गई है या अनुमति नहीं है। `x-api-key` header सत्यापित करें।
`500 Internal Server Error`	`internal server error`	Server-side प्रसंस्करण विफलता। exponential backoff के साथ पुनः प्रयास करें। यदि लगातार हो, तो support को रिपोर्ट करें।

उदाहरण 400 प्रतिक्रिया:

{
  "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 को उपयोगकर्ता को वितरित करें

WhatsApp, SMS, ईमेल के माध्यम से भेजें या embed करें। उपयोगकर्ता अपने स्वयं के डिवाइस पर लिंक एक्सेस करता है और होस्टेड यात्रा पूरी करता है।

यदि आप ब्राउज़र में लिंक खोलने के बजाय यात्रा को अपने स्वयं के ऐप के अंदर embed करना पसंद करते हैं, तो आप ऐसा WebView या CustomTab के माध्यम से कर सकते हैं। संदर्भ PoCs:

Android/Kotlin: TrullyAi-AndroidMagicLink
React Native: TrullyAI-ReactNativeMagicLink

4. परिणाम प्राप्त करें

आपके पास यह तय करने की पूरी flexibility है कि KYC प्रक्रिया का अंतिम परिणाम कैसे प्राप्त करें — वह strategy चुनें जो आपके सिस्टम के architecture के लिए सबसे उपयुक्त हो। आप सक्रिय रूप से परिणाम के लिए poll कर सकते हैं (GET) या इसे notifications (Webhook) के माध्यम से passively प्राप्त कर सकते हैं।

विकल्प A — GET के माध्यम से सक्रिय Polling

GET /v2/history/request?magic_link_token={token} को call करके परिणाम प्राप्त करें (नीचे GET के माध्यम से Polling देखें)। अंतिम निर्णय data.response.unico.result में populated होता है।

GET के लिए सर्वोत्तम प्रथा

लिंक बनाए जाने के क्षण से समय-समय पर poll करने के बजाय, यह जानने के लिए कि कब query करना है, tracking webhooks (नीचे Webhook V2 देखें) का उपयोग करें। एक बार जब आपको form_decision_maker चरण प्राप्त हो जाए, तो यह इस GET call को trigger करने का सटीक, सुरक्षित क्षण है।

विकल्प B — Webhook के माध्यम से स्वचालित प्राप्ति

अपने सिस्टम को स्वचालित रूप से सूचित करवाएं जैसे ही अंतिम परिणाम तैयार हो (नीचे Webhook V2 देखें)। दो versions उपलब्ध हैं:

Webhook V1 — टोकन बनाते समय metadata.webhook_url में भेजे गए URL पर आपको परिणाम प्राप्त होता है।
Webhook V2 — पहले से अपने Onboarding PM के साथ कॉन्फ़िगर किया गया। आप MAGIC_LINK_RESULTS event को सुनकर अंतिम निर्णय प्राप्त करते हैं।

Resilience — fallback

यदि Webhook (विकल्प B) आपकी प्राथमिक विधि है, तो fallback के रूप में GET query (विकल्प A) को भी implement करें। यह आपको network विफलताओं, अस्थायी server outages, या ठीक से process न होने वाले webhook की स्थिति में reconciliation routines के माध्यम से परिणाम पुनर्प्राप्त करने देता है।

GET के माध्यम से Polling

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

Query parameters:

Parameter	Type	आवश्यक	विवरण
`magic_link_token`	string	हां	Magic Link बनाए जाने पर लौटाया गया टोकन।

Headers:

Header	आवश्यक	विवरण
`x-api-key`	हां	Unico में आपके Onboarding Project Manager द्वारा प्रावधानित API key।

उदाहरण अनुरोध:

curl "https://sandbox.trully.ai/v2/history/request?magic_link_token=$TOKEN" \
  -H "x-api-key: $TRULLY_API_KEY"

उदाहरण प्रतिक्रिया:

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

प्रतिक्रिया fields:

Root level:

Field	Type	विवरण
`status`	string	प्रतिक्रिया स्थिति का पाठ्य प्रतिनिधित्व।
`status_code`	integer	HTTP status code।
`request_date`	string (date-time)	अनुरोध किए जाने की तारीख और समय।
`version`	string	API संस्करण जिसने अनुरोध संसाधित किया।
`data.user_id`	string	मूल अनुरोध में सेट किया गया user ID।

data.images — Base64-encoded कैप्चर की गई छवियां:

Field	Type	विवरण
`data.images.document_image`	string	दस्तावेज़ के सामने की Base64-encoded छवि।
`data.images.document_image_back`	string	दस्तावेज़ के पीछे की Base64-encoded छवि।
`data.images.selfie`	string	सत्यापन के दौरान कैप्चर की गई Base64-encoded सेल्फी छवि।

data.response.unico — समेकित निर्णय:

Field	Type	विवरण
`data.response.unico.process_id`	string (UUID)	सत्यापन प्रक्रिया से संबंधित आंतरिक पहचानकर्ता।
`data.response.unico.result`	string	प्रक्रिया परिणाम। संभावित मान नीचे वर्णित हैं।

data.response.unico.result के संभावित मान:

परिणाम मान तीन मूल्यांकन आयामों में से एक को encode करता है:

पहचान मूल्यांकन — क्या कैप्चर किया गया चेहरा दस्तावेज़ धारक का है (PROCESS_RESULT_VERIFIED, PROCESS_RESULT_NOT_APPROVED)।
धोखाधड़ी व्यवहार — क्या व्यवहार संबंधी या नेटवर्क संकेत धोखाधड़ी के जोखिम का संकेत देते हैं (PROCESS_RESULT_LIVE, PROCESS_RESULT_HIGH_RISK, PROCESS_RESULT_CRITICAL_RISK, PROCESS_RESULT_NOT_APPROVED)।
Liveness — क्या कैप्चर के समय एक जीवित चेहरा पाया गया (PROCESS_RESULT_NOT_LIVE)।

परिणाम	अनुशंसा	अर्थ	संकेत
`PROCESS_RESULT_ERROR`	अस्वीकार करें	प्रक्रिया त्रुटि के साथ समाप्त हुई।	सिस्टम
`PROCESS_RESULT_VERIFIED`	स्वीकार करें	उपयोगकर्ता कैप्चर के समय सक्रिय था; यह ID धारक का चेहरा है और धोखाधड़ी से संबंधित कोई सबूत नहीं मिला।	पहचान: पुष्टि की गई
`PROCESS_RESULT_LIVE`	समीक्षा / स्वीकार करें	उपयोगकर्ता कैप्चर के समय सक्रिय था; हमें यह गारंटी देने के लिए पर्याप्त सबूत नहीं मिले कि वे ID धारक हैं और धोखाधड़ी का कोई सबूत नहीं है।	पहचान: अनिर्णायक · धोखाधड़ी: कोई नहीं
`PROCESS_RESULT_HIGH_RISK`	अस्वीकृति की अनुशंसा करें	हमें धोखाधड़ी का कम से कम एक मजबूत सबूत मिला। अंतिम निर्णय आपका है।	धोखाधड़ी व्यवहार: 1 मजबूत संकेत
`PROCESS_RESULT_CRITICAL_RISK`	अस्वीकृति की अनुशंसा करें	हमें धोखाधड़ी के कम से कम 2 मजबूत सबूत मिले। अंतिम निर्णय आपका है।	धोखाधड़ी व्यवहार: 2+ मजबूत संकेत
`PROCESS_RESULT_NOT_APPROVED`	अस्वीकार करें	धोखाधड़ी के कई संकेत पाए जाने के कारण अस्वीकृति की अनुशंसा की जाती है।	पहचान: अस्वीकृत · धोखाधड़ी व्यवहार: कई संकेत
`PROCESS_RESULT_NOT_LIVE`	2 पुनः प्रयास तक अनुमति दें	कैप्चर के समय उपयोगकर्ता जीवित नहीं था, हालांकि हमें धोखाधड़ी के कोई अन्य संकेत नहीं मिले।	Liveness: चेहरा जीवित नहीं

नोट

PROCESS_RESULT_VERIFIED सक्रियण की आवश्यकता है। डिफ़ॉल्ट रूप से, यह परिणाम सक्रिय नहीं है — यदि आप इसे सक्षम करना चाहते हैं तो अपने Unico Project Manager के साथ संरेखित करें।

आपके निर्णय के लिए सहायक संकेत:

LIVE, HIGH_RISK या CRITICAL_RISK मामलों के लिए, इन fields के साथ अपना निर्णय पूरा करें:

Field	Type	अर्थ
`face_match`	boolean	दस्तावेज़ और सेल्फी के बीच चेहरे के मिलान की स्थिति।
`document.front.face_analysis.match_fraud_flag`	boolean	क्या दस्तावेज़ का चेहरा धोखाधड़ी गतिविधि से जुड़ा हुआ है।
`selfie.match_fraud_flag`	boolean	क्या सेल्फी का चेहरा धोखाधड़ी गतिविधि से जुड़ा हुआ है।
`warnings.external_id`	string	चेतावनी यह दर्शाती है कि उपयोगकर्ता का चेहरा कई external IDs से जुड़ा हुआ है।

data.response — शीर्ष-स्तरीय परिणाम संकेत:

Field	Type	विवरण
`data.response.face_match`	boolean	क्या सेल्फी का चेहरा दस्तावेज़ के चेहरे से मेल खाता है।
`data.response.label`	string (nullable)	विशिष्ट उप-प्रक्रियाओं के परिणामों के लिए आरक्षित; यदि लागू नहीं तो `null`।
`data.response.reason`	string (nullable)	असाइन किए गए label के कारण।
`data.response.request_id`	string	API अनुरोध के लिए अद्वितीय पहचानकर्ता।

data.response.curp — RENAPO के विरुद्ध CURP सत्यापन:

Field	Type	विवरण
`curp`	string	विश्लेषण किया जा रहा CURP string।
`government_valid`	boolean	क्या RENAPO के अनुसार CURP वैध है।
`government_name`	string	आधिकारिक डेटाबेस में CURP से जुड़ा पूरा नाम।
`name_to_CURP_valid`	boolean	क्या प्रदान किया गया नाम CURP के साथ सुसंगत है।
`is_mexican`	boolean	क्या CURP मैक्सिकन नागरिक से मेल खाता है।
`deceased`	boolean	क्या CURP आधिकारिक डेटाबेस में मृत के रूप में चिह्नित है।
`date_of_birth`	string	CURP से डीकोड की गई जन्म तारीख (DD/MM/YYYY)।
`age`	integer	उपयोगकर्ता की गणना की गई आयु।
`gender`	string	CURP से डीकोड किया गया लिंग (`M` या `F`)।
`state_of_birth`	string	CURP से डीकोड किया गया जन्म राज्य।
`state_iso`	string	जन्म राज्य के लिए ISO 3166-2 code।

data.response.document.details — दस्तावेज़ पहचान और forensics:

Field	Type	विवरण
`detected`	boolean	क्या छवि में कोई दस्तावेज़ सफलतापूर्वक पहचाना गया।
`document_id`	integer	संसाधित दस्तावेज़ के लिए अद्वितीय पहचानकर्ता।
`forensics.is_valid`	string	Forensic विश्लेषण परिणाम: `yes`, `no` या `inconclusive`।

data.response.document.front.information — INE front से OCR-निकाले गए fields। प्रत्येक field में text (निकाला गया मान) और valid (क्या इसे संरचनात्मक रूप से मान्य किया जा सका) शामिल हैं:

Field	विवरण
`name`	पहला नाम।
`last_name`	पिता का उपनाम।
`mother_last_name`	माता का उपनाम।
`complete_name`	पूरा नाम।
`birthdate`	जन्म तारीख (DD/MM/YYYY)।
`sex`	लिंग (`H` या `M`)।
`curp`	दस्तावेज़ से निकाला गया CURP।
`electoral_key`	चुनावी key।
`address`	पता।
`registration_year`	दस्तावेज़ पंजीकृत होने का वर्ष।
`valid_thru`	दस्तावेज़ समाप्ति वर्ष।

data.response.document.front.face_analysis — INE पर पाए गए चेहरे का विश्लेषण:

Field	Type	विवरण
`face_id`	integer	इस चेहरे instance के लिए अद्वितीय पहचानकर्ता।
`face_id_v2`	integer	अद्वितीय पहचानकर्ता (संस्करण 2)।
`unique_face_id_v2`	integer	सभी inquiries में इस भौतिक चेहरे के लिए persistent पहचानकर्ता।
`first_seen`	string	सिस्टम में इस चेहरे को पहली बार देखे जाने का timestamp।
`last_seen`	string	नेटवर्क में इस चेहरे को सबसे हाल ही में देखे जाने का timestamp।
`last_seen_by_your_company`	string	आपकी कंपनी की inquiry में इस चेहरे को सबसे हाल ही में देखे जाने का समय।
`inquiry_date`	string	वर्तमान सत्यापन inquiry का timestamp।
`match`	boolean	क्या यह चेहरा डेटाबेस के अन्य चेहरों के साथ संभावित मेल है।
`match_fraud_flag`	boolean	क्या यह चेहरा धोखाधड़ी गतिविधि से जुड़ा हुआ है।
`seen_by_your_company`	boolean	क्या यह चेहरा पहले आपकी कंपनी ने देखा था।
`seen_different_companies`	integer	नेटवर्क की अन्य कंपनियों की संख्या जिन्होंने इस चेहरे को देखा है।
`times_seen_by_your_company`	integer	आपकी कंपनी की inquiries में इस चेहरे को देखे जाने की कुल संख्या।
`times_seen_last_month`	integer	नेटवर्क में पिछले महीने देखे जाने की संख्या।
`warnings.external_id`	string	चेतावनी यदि उपयोगकर्ता का चेहरा कई external IDs से जुड़ा हुआ है।

data.response.document.back — INE back से MRZ डेटा:

Field	Type	विवरण
`mrz`	string	पूरा Machine-Readable Zone string।
`cic`	string	MRZ से निकाला गया CIC नंबर।
`citizen_id`	string	MRZ से नागरिक पहचान संख्या।

data.response.selfie — कैप्चर की गई सेल्फी का विश्लेषण:

Field	Type	विवरण
`face_id`	integer	सेल्फी चेहरे instance के लिए अद्वितीय पहचानकर्ता।
`face_id_v2`	integer	अद्वितीय पहचानकर्ता (संस्करण 2)।
`unique_face_id_v2`	integer	सभी inquiries में इस भौतिक चेहरे के लिए persistent पहचानकर्ता।
`first_seen`	string	सिस्टम में इस सेल्फी के चेहरे को पहली बार देखे जाने का समय।
`first_seen_image`	boolean	क्या यह पहली बार है जब यह सटीक छवि देखी गई।
`last_seen`	string	नेटवर्क में इस चेहरे को सबसे हाल ही में देखे जाने का समय।
`last_seen_by_your_company`	string	आपकी कंपनी द्वारा इस चेहरे को सबसे हाल ही में देखे जाने का समय।
`inquiry_date`	string	वर्तमान सत्यापन inquiry का timestamp।
`match`	boolean	क्या सेल्फी का चेहरा डेटाबेस के अन्य चेहरों से मेल खाता है।
`match_fraud_flag`	boolean	क्या सेल्फी का चेहरा धोखाधड़ी गतिविधि से जुड़ा हुआ है।
`seen_by_your_company`	boolean	क्या यह चेहरा पहले आपकी कंपनी ने देखा था।
`seen_different_companies`	integer	नेटवर्क की अन्य कंपनियों की संख्या जिन्होंने इस चेहरे को देखा है।
`times_seen_by_your_company`	integer	आपकी कंपनी की inquiries में इस चेहरे को देखे जाने की कुल संख्या।
`times_seen_last_month`	integer	नेटवर्क में पिछले महीने देखे जाने की संख्या।
`warnings`	object	सेल्फी विश्लेषण से संबंधित विशिष्ट चेतावनियां (document face_analysis जैसी ही संरचना)।

exponential backoff के साथ polling का उपयोग करें — tight loop में call न करें।

त्रुटि प्रतिक्रियाएं — GET /v2/history/request

Code	Message	विवरण
`400 Bad Request`	`Input should be a valid UUID, invalid group length...`	`magic_link_token` parameter विकृत है या वैध UUID प्रारूप नहीं है।
`404 Not Found`	`This magic link have no requests associated`	प्रदान किया गया टोकन मौजूद है लेकिन उससे जुड़ी कोई पूर्ण KYC प्रक्रियाएं नहीं हैं। उपयोगकर्ता ने अभी तक यात्रा पूरी नहीं की होगी।
`500 Internal Server Error`	`internal server error`	Server-side प्रसंस्करण विफलता। exponential backoff के साथ पुनः प्रयास करें। यदि लगातार हो, तो support को रिपोर्ट करें।

उदाहरण 400 प्रतिक्रिया:

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

उदाहरण 404 प्रतिक्रिया:

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

उदाहरण 500 प्रतिक्रिया:

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

तीन webhook events उपलब्ध हैं। सक्रिय करने के लिए, अपने Onboarding Project Manager से यह प्रदान करते हुए सेटअप का अनुरोध करें: endpoint URL (HTTPS आवश्यक), auth type (basic_auth, api_key, oauth2 या NoAuth), auth कॉन्फ़िगरेशन, अधिकतम पुनः प्रयास, पुनः प्रयास अंतराल (s) और timeout (s)।

MAGIC_LINK_RESULTS

यह event प्रवाह के अंत में भेजा जाता है, जब Decision Maker ने भेजी गई जानकारी का प्रसंस्करण पूरा कर लिया हो।

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

ये events तब प्राप्त होते हैं जब उपयोगकर्ता ने कोई कार्य पूरा किया हो। उदाहरण के लिए, form_start तब प्राप्त होगा जब उपयोगकर्ता दस्तावेज़ का सामने का हिस्सा ले रहा हो, जिसका अर्थ है कि उपयोगकर्ता ने क्लिक किया और पहली स्क्रीन पूरी की।

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

Field	Type	विवरण
`data.step`	string	पूर्ण किए गए चरण का नाम।
`data.user_id`	string (nullable)	magic link में सेट किया गया external ID।
`data.started_on`	datetime	UTC timezone चरण प्रारंभ समय।
`data.completed_on`	datetime	UTC timezone चरण पूर्णता समय।
`event`	string	Event type पहचानकर्ता।
`magic_link_token`	uuid	अद्वितीय magic link टोकन।
`user_id`	string (nullable)	बाहरी पहचानकर्ता।
`date`	datetime	Event timestamp।

समर्थित चरण:

Step	विवरण
`form_start`	उपयोगकर्ता ने प्रारंभिक magic link बटन क्लिक किया।
`form_document_front`	उपयोगकर्ता ने INE front कैप्चर पूरा किया।
`form_document_back`	उपयोगकर्ता ने INE back कैप्चर पूरा किया।
`form_document`	उपयोगकर्ता ने front और back दोनों प्रक्रियाएं पूरी कीं।
`form_selfie`	उपयोगकर्ता ने liveness प्रक्रिया पूरी की।
`form_decision_maker`	उपयोगकर्ता ने पूरा प्रवाह पूरा किया।

MAGIC_LINK_DOCUMENT_RETAKE_REASONS

यह event तब भेजा जाता है जब दस्तावेज़ की पुनः कैप्चर आवश्यक हो, चाहे front या back प्रक्रिया के दौरान। यह दर्शाता है कि INE से महत्वपूर्ण डेटा नहीं पढ़ा जा सका।

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

Field	Type	विवरण
`data.document_type`	string	दस्तावेज़ पक्ष: `ine_front` या `ine_back`।
`data.invalid_document`	boolean	`true` यदि कैप्चर की गई छवि वैध INE नहीं है (किसी भी पक्ष)।
`data.invalid_curp`	boolean	`true` यदि CURP पढ़ा नहीं जा सका (`ine_front` केवल)।
`data.invalid_back_ocr`	boolean	`true` यदि MRZ code पढ़ा नहीं जा सका (`ine_back` केवल)।
`event`	string	Event type पहचानकर्ता।
`magic_link_token`	uuid	अद्वितीय magic link टोकन।
`user_id`	string (nullable)	बाहरी पहचानकर्ता।
`date`	datetime	Event timestamp।

payload इस तरह से डिज़ाइन किया गया है कि प्रत्येक दस्तावेज़ पक्ष के लिए केवल एक त्रुटि (true) प्राप्त होती है।

विफलता परिदृश्य — INE front:

अमान्य दस्तावेज़ → केवल invalid_document: true
CURP पढ़ने की विफलता → केवल invalid_curp: true

विफलता परिदृश्य — INE back:

अमान्य दस्तावेज़ → केवल invalid_document: true
MRZ पढ़ने की विफलता → केवल invalid_back_ocr: true

V1 / V2 संगतता

यदि आप अभी भी अनुरोध के metadata में webhook_url भेजते हैं (Webhook V1), तो वह कॉन्फ़िगरेशन global V2 पर प्राथमिकता लेता है। माइग्रेट करने के लिए, metadata से webhook_url हटाएं और अपने Onboarding PM के साथ V2 कॉन्फ़िगर करें।

अनुकूलन

होस्टेड Magic Link page क्लाइंट द्वारा दृश्य अनुकूलन का समर्थन नहीं करता — यह डिफ़ॉल्ट Unico/Trully दृश्य पहचान का पालन करता है। यात्रा को अनुकूलित करने के लिए (लोगो, रंग, टेक्स्ट), SDK या Web के साथ Onboarding (Global) का उपयोग करें।

उपलब्धता: मेक्सिको · Endpoint: POST https://api.trully.ai/v2/magic-link · दस्तावेज़: INE · Auth: x-api-key (Trully)

यह उपयोग मामला क्या हल करता है​

शामिल क्षमताएं​

पूर्वापेक्षाएं​

चरण-दर-चरण कार्यान्वयन​

1. Magic Link बनाएं​

2. टोकन और लिंक URL प्राप्त करें​

3. magic_link_url को उपयोगकर्ता को वितरित करें​

4. परिणाम प्राप्त करें​

GET के माध्यम से Polling​

Webhook V2​

अनुकूलन​