मुख्य सामग्री पर जाएँ
ShieldID

API संदर्भ

पहचान सत्यापन API का संदर्भ।

हर endpoint जिसे आप कॉल कर सकते हैं, हर फ़ील्ड जो आपको वापस दिखेगा, और webhook आने के बाद उसका क्या करना है। फ़ील्ड के सटीक प्रकार के लिए, अपने API origin के /docs पर मौजूद लाइव OpenAPI दस्तावेज़ को प्रामाणिक स्रोत मानें — यह पृष्ठ उसका सरल भाषा वाला रूप है।

क्विकस्टार्ट पढ़ेंsandbox की प्राप्त करें

बेस URL और परिवेश

एक बेस URL। दो परिवेश।

हर रिक्वेस्ट उसी होस्ट पर जाती है। आप किस परिवेश में हैं, यह पूरी तरह इससे तय होता है कि आप कौन-सी API कुंजी भेजते हैं।

इस रेफ़रेंस का हर अनुरोध इन दो बातों को मानकर चलता है।
बेस URL (यह दस्तावेज़ीकरण)https://api.shieldid.ca — illustrative; your production API origin is published together with your API keys.
ऑथ हेडरX-Api-Key: <आपकी की>, हर रिक्वेस्ट पर, नीचे बताए गए दो सार्वजनिक एंडपॉइंट को छोड़कर।
Sandbox की का प्रीफ़िक्सvk_sand_… — इस की से बनाए गए सेशन पर environment: "sandbox" अंकित होता है और उनका कभी बिल नहीं बनता।
प्रोडक्शन की का प्रीफ़िक्सvk_live_… — वही रिक्वेस्ट, आपके प्लान के अनुसार शुल्क के साथ।
कंटेंट टाइपहर रिक्वेस्ट बॉडी और रिस्पॉन्स पर application/json।

एंडपॉइंट

पूरा v1 सरफ़ेस।

छह JSON एंडपॉइंट, साथ में एक होस्टेड पेज और एक सार्वजनिक क्रेडेंशियल जाँच जो बिल्कुल भी JSON नहीं हैं — आप बस उनका लिंक देते हैं।

/v1 के अंतर्गत JSON endpoints।
EndpointAuthWhat it does
POST /v1/sessionsX-Api-Keyसत्यापन सेशन बनाएँ। return_url और webhook_url आवश्यक हैं। session_id, verification_url और status: "PENDING" लौटाता है।
GET /v1/sessions/{id}X-Api-Keyएक सेशन की स्थिति और मुख्य फ़ील्ड: status, confidence, environment।
GET /v1/sessions/{id}/resultX-Api-Keyसेशन के VERIFIED या FAILED तक पहुँचने पर पूरा परिणाम: person, प्रति-जाँच निर्णय, confidence, verified_until।
DELETE /v1/sessions/{id}X-Api-Keyऐसे सेशन को रद्द करें जो अभी भी PENDING या IN_PROGRESS है। जो सेशन पहले से VERIFIED, FAILED या EXPIRED है, उसे रद्द नहीं किया जा सकता।
GET /v1/credentials/{token}None — publicजाँचें कि कोई सत्यापित क्रेडेंशियल अभी मान्य है या नहीं। API key आवश्यक नहीं है, इसलिए इसे ब्राउज़र से कॉल किया जा सकता है। ध्यान दें: आज का रिस्पॉन्स केवल valid/invalid फ़्लैग ही नहीं, बल्कि सत्यापित व्यक्ति का नाम और दस्तावेज़ का प्रकार/देश भी देता है — यह लिंक ऐसे किसी तीसरे पक्ष को न दें जिसे आप यह जानकारी नहीं दिखाना चाहते।
GET /v1/pricing/{country}X-Api-Keyदो-अक्षरों वाले ISO 3166-1 देश कोड के लिए देश-वार मूल्य निर्धारण।
ऐसे पृष्ठ जिन्हें आप लिंक करते हैं, ऐसा JSON नहीं जिसे आप पार्स करते हैं।
/v/{session_id}होस्टेड सत्यापन पेज — वही verification_url जो सेशन लौटाता है। डेस्कटॉप पर QR कोड दिखता है; उसे स्कैन करने पर आवेदक के फ़ोन पर वही लिंक खुलता है, जिससे वह अपना दस्तावेज़ और सेल्फ़ी कैप्चर कर सके।
/c/{session_id}एक सत्यापित सेशन के लिए सार्वजनिक, बिना प्रमाणीकरण वाला क्रेडेंशियल-जाँच पेज। ध्यान दें: आज का रिस्पॉन्स केवल valid/invalid फ़्लैग ही नहीं, बल्कि सत्यापित व्यक्ति का नाम और दस्तावेज़ का प्रकार/देश भी देता है — यह लिंक ऐसे किसी तीसरे पक्ष को न दें जिसे आप यह जानकारी नहीं दिखाना चाहते।
/docsआपके खाते के API ओरिजिन के लिए लाइव, इंटरैक्टिव OpenAPI संदर्भ।

सेशन बनाना

POST /v1/sessions, शुरू से अंत तक।

अनुरोध, और बदले में ठीक क्या मिलता है।

bash
curl -X POST https://api.shieldid.ca/v1/sessions \
  -H "X-Api-Key: vk_sand_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "return_url": "https://yourapp.example/verified",
    "webhook_url": "https://yourapp.example/hooks/shieldid",
    "expected_name": "Jordan Smith",
    "locale": "en",
    "metadata": { "application_id": "app_9182" }
  }'

POST /v1/sessions — रिक्वेस्ट फ़ील्ड।
return_urlstring, आवश्यक — आवेदक के प्रक्रिया पूरी करने के बाद उसे जहाँ वापस भेजा जाता है। http या https होना चाहिए।
webhook_urlstring, आवश्यक — जहाँ साइन किया हुआ परिणाम भेजा जाता है। नीचे Webhooks देखें।
expected_namestring, आवश्यक — दस्तावेज़ पर आपके अपेक्षित नाम, जिसका उपयोग यह मिलान करने के लिए होता है कि ID पर वास्तव में क्या लिखा है।
expected_dob / expected_addressstring, वैकल्पिक — देने पर दस्तावेज़ से मिलान किया जाता है; सत्यापन चलाने के लिए आवश्यक नहीं है।
localestring, वैकल्पिक — "en" या "fr"। आवेदक को दिखने वाले होस्टेड पेज की भाषा तय करता है।
metadataobject, वैकल्पिक — आपका अपना संदर्भ डेटा — एप्लिकेशन id, टेनेंट id, या कुछ भी जिसे आप परिणाम और webhook में बिना बदलाव के वापस पाना चाहते हैं।

परिणाम

GET /v1/sessions/{id}/result — रिस्पॉन्स की संरचना।

वही संरचना webhook पेलोड में भी भेजी जाती है, इसलिए आपको इस एंडपॉइंट को पोल करने की शायद ही कभी ज़रूरत पड़ती है।

शीर्ष-स्तर के फ़ील्ड।
session_idवह id जो आपने बनाई थी।
statusPENDING, IN_PROGRESS, VERIFIED, FAILED या EXPIRED।
environment"sandbox" या "production", सेशन बनाने वाली की के अनुसार।
personदस्तावेज़ से पढ़े गए फ़ील्ड: नाम, जन्मतिथि, दस्तावेज़ का प्रकार, दस्तावेज़ का देश और क्षेत्राधिकार, पता।
checksहर जाँच के लिए एक निर्णय — नीचे देखें। कभी कोई एक अस्पष्ट स्कोर नहीं।
confidenceसत्यापन के लिए एक समग्र आँकड़ा। फ़ेस मैच सहित अलग-अलग जाँचें फिर भी एक तय निर्णय रेखा के विरुद्ध अपने-आप रिपोर्ट होती हैं — यह फ़ील्ड उनकी जगह नहीं लेता।
verified_untilVERIFIED सेशन पर, परिणाम कितने समय तक मान्य माना जाता है।
failure_reasonFAILED सेशन पर सेट होता है — उदाहरण के लिए FACE_MATCH_BELOW_THRESHOLD या CANCELLED_BY_API। अन्यथा null।
metadataसेशन बनाते समय आपने जो भी भेजा था, बिना किसी बदलाव के।
json
{
  "session_id": "ses_9f2c1a",
  "status": "VERIFIED",
  "environment": "sandbox",
  "person": {
    "name": "Jordan Smith",
    "dob": "1994-03-11",
    "document_type": "drivers_licence",
    "document_country": "CA",
    "document_jurisdiction": "ON"
  },
  "checks": {
    "document": "PASS",
    "liveness": "PASS",
    "antispoof": "PASS",
    "face_match": "PASS"
  },
  "confidence": 88,
  "verified_until": "2027-03-11T00:00:00Z",
  "failure_reason": null,
  "metadata": { "application_id": "app_9182" }
}

Add-onchecks.document, checks.liveness, checks.antispoof और checks.face_match में से हर एक PASS, FAIL या SKIPPED में तय होता है। वॉचलिस्ट स्क्रीनिंग (checks.sanctions — CLEAR, MATCH या SKIPPED) एक ऐड-ऑन है और केवल उन खातों के लिए दिखती है जो इसे चालू करते हैं।

सेशन जीवनचक्र

पाँच अवस्थाएँ, एक रास्ता।

सेशन अपने-आप आगे बढ़ता है; आप स्टेट मशीन को नहीं चलाते, बस उसे पढ़ते हैं।

status मान, क्रम में।
PENDINGबनाया गया। अभी किसी ने verification_url नहीं खोला है।
IN_PROGRESSआवेदक ने लिंक खोल लिया है और कैप्चर प्रक्रिया में कहीं है।
VERIFIEDहर जाँच चल चुकी है और परिणाम तैयार है। अंतिम अवस्था — result endpoint को कॉल करें या webhook पढ़ें।
FAILEDकम से कम एक जाँच पास नहीं हुई। failure_reason बताता है कि कौन-सी। जल्द आ रहा है: एक रीट्राई जो सेशन को PENDING पर रीसेट कर देगा — तब तक FAILED को अंतिम अवस्था मानें और आवेदक दोबारा कोशिश करना चाहे तो नया सेशन बनाएँ।
EXPIREDसमय पर किसी ने पूरा नहीं किया। सेशन एक डिफ़ॉल्ट अवधि (30 मिनट) के बाद अपने-आप समाप्त हो जाते हैं; दोबारा कोशिश के लिए नया बनाएँ।

DELETE /v1/sessions/{id} किसी PENDING या IN_PROGRESS सेशन को समय से पहले रद्द कर देता है। जो सेशन पहले ही VERIFIED, FAILED या EXPIRED तक पहुँच चुका है, उसे रद्द नहीं किया जा सकता — वह पहले ही पूरा हो चुका है।

त्रुटियाँ

किन बातों के लिए तैयार रहें।

यह वह संक्षिप्त सूची है जिसके अनुसार आज कोड लिखना उचित है। त्रुटि कोड और पेलोड का पूरा, ताज़ा सेट /docs पर लाइव OpenAPI में दिया गया है।

HTTP स्टेटस, एरर कोड और उसका अर्थ।
StatusCodeMeaning
401UNAUTHORIZEDX-Api-Key हेडर मौजूद नहीं है।
401INVALID_KEY_FORMATकुंजी vk_sand_ या vk_live_ से शुरू नहीं होती, या खाते की किसी कुंजी से मेल नहीं खाती।
403FORBIDDENकुंजी मान्य है, लेकिन आपने जिस सेशन या संसाधन का अनुरोध किया उस तक उसकी पहुँच नहीं है।
404NOT_FOUNDउस id वाला कोई सेशन, क्रेडेंशियल या संसाधन मौजूद नहीं है।
409CONFLICTसेशन ऐसी स्थिति में नहीं है जिसमें यह कार्रवाई की जा सके — उदाहरण के लिए, ऐसे सेशन को रद्द करना जो पहले से VERIFIED है।
422VALIDATION_ERRORकोई ज़रूरी फ़ील्ड गायब है या गलत रूप में है — उदाहरण के लिए, return_url मान्य http या https URL नहीं है।

Webhooks

हस्ताक्षरित, डिलीवर, रीट्राई।

जब कोई सेशन VERIFIED या FAILED तक पहुँचता है, तो ShieldID ऊपर दर्ज संरचना को आपके webhook_url पर POST करता है।

  • ऊपर दी गई परिणाम संरचना से मेल खाती JSON बॉडी के साथ POST के रूप में डिलीवर किया जाता है।
  • कच्ची रिक्वेस्ट बॉडी पर HMAC-SHA256 से हस्ताक्षरित, और X-Bio-Signature हेडर में भेजा जाता है। पेलोड पर भरोसा करने से पहले उसे अपने webhook secret के विरुद्ध सत्यापित करें।
  • यदि आपका endpoint 2xx स्टेटस से उत्तर नहीं देता, तो रैखिक बैकऑफ़ के साथ अधिकतम तीन बार रीट्राई किया जाता है।
  • जल्द आ रहा है: FAILED सेशन की रीट्राई, जो हल होने पर दूसरा webhook भेजेगी। आज के लिए, प्रति सेशन एक webhook को नियम मानें।
  • यहाँ के फ़ील्ड नाम इस संदर्भ से मेल खाते हैं। यदि वास्तव में जो आए वह अलग दिखे, तो इस पृष्ठ की बजाय लाइव पेलोड पर भरोसा करें और हमें बताएँ — फ़ील्ड सूची API के अनुरूप रखी जाती है, उल्टा नहीं।

हस्ताक्षर सत्यापित करें

javascript
import crypto from "node:crypto";

function isValidShieldIdSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const provided = signatureHeader || "";
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(provided, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// rawBody must be the exact, unparsed request body
app.post("/hooks/shieldid", express.raw({ type: "application/json" }), (req, res) => {
  const ok = isValidShieldIdSignature(req.body, req.headers["x-bio-signature"], process.env.SHIELDID_WEBHOOK_SECRET);
  if (!ok) return res.status(401).send("invalid signature");

  const result = JSON.parse(req.body);
  // result.session_id, result.status, result.checks, …
  res.status(200).send("ok");
});

आइडेम्पोटेंसी और रीट्राई

ऐसे हैंडलर बनाएँ जो दो बार चलने पर भी सुरक्षित हों।

अभी सेशन बनाने या webhook डिलीवरी, किसी के लिए भी कोई समर्पित आइडेम्पोटेंसी कुंजी नहीं है।

  • रीट्राई की गई webhook डिलीवरी एक ही सेशन के लिए एक से ज़्यादा बार आ सकती है। अपने हैंडलर को session_id + status पर आधारित करें और परिणाम लिखने को आइडेम्पोटेंट बनाएँ।
  • टाइमआउट होने पर POST /v1/sessions को आँख मूँदकर रीट्राई न करें — पहले जाँचें कि सेशन बना था या नहीं, वरना एक आवेदक के लिए दो सेशन बन सकते हैं।
  • सेशन बनाने के लिए एक समर्पित Idempotency-Key हेडर की योजना है।

जल्द आ रहा हैसेशन बनाने पर Idempotency-Key का समर्थन

अपडेट रहें

यह संदर्भ बदलता रहता है। चेंजलॉग देखते रहें।

फ़ील्ड जोड़ने, नए त्रुटि कोड और endpoint बदलावों की घोषणा यहाँ आने से पहले वहाँ की जाती है।

चेंजलॉग पढ़ें

प्रश्न

रेफ़रेंस FAQ।

आगे

इस संदर्भ का उपयोग शुरू करें।

क्विकस्टार्ट का पालन करके क्रम से sandbox की से लेकर सत्यापित सेशन और साइन किए गए webhook तक पहुँचें।

क्विकस्टार्ट पढ़ेंsandbox में मुफ़्त शुरू करें