प्रोसेस बनाएँPOST

एक प्रोसेस शुरू करें और Human Token तथा व्यक्ति की इंटेलिजेंस प्राप्त करें।

Markdown

POST /v1/processes

फ़्लो में से किसी एक के साथ प्रोसेस शुरू करता है और id, state तथा data में परिणाम के साथ उत्तर देता है: Human Token और व्यक्ति की इंटेलिजेंस, data.ndocs।

कॉल करने से पहले

• Human Plugin चल रहा है और GET /health/ready 200 लौटाता है।
• आपकी एक्सेस की उस फ़्लो के लिए सक्षम है जिसे आप उपयोग करते हैं।
• यदि आप कोई दस्तावेज़ भेजते हैं, तो उसका type एट्रिब्यूट कैटलॉग में है।

फ़्लो

flow फ़ील्ड तय करता है कि प्रोसेस क्या करेगा। Human Plugin ये फ़्लो दो एकीकरण मॉडल में चलाता है:

• API Only: आपका बैक-एंड सेल्फ़ी को imageBase64 में भेजता है, और create परिणाम के साथ उत्तर देता है।
• Human Token Journey: व्यक्ति कैप्चर जर्नी में सेल्फ़ी लेता है और आपके callbackUri पर लौटता है। create एक token और एक link के साथ उत्तर देता है, और आप परिणाम प्रोसेस प्राप्त करें से पढ़ते हैं।

Flow	Description	Possible result	Integration components required	Example
api+humantoken	आपके बैक-एंड के माध्यम से सेल्फ़ी प्राप्त करता है और Human Token बनाता है, जो एक अद्वितीय चेहरा पहचानकर्ता है। उत्तर अंतिम होता है: कोई कैप्चर नहीं, कोई दूसरी कॉल नहीं।	PROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	API
humantoken	कैप्चर जर्नी में लाइवनेस जाँच के साथ सेल्फ़ी कैप्चर करता है और Human Token बनाता है। create `token` और `link` लौटाता है; कैप्चर समाप्त होने पर परिणाम पढ़ें।	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb
humantoken+revalidation	सेल्फ़ी कैप्चर करता है और चेहरे की तुलना आपके अपेक्षित Human Token से करता है। बताता है कि वह वही व्यक्ति है या नहीं, उदाहरण के लिए किसी संवेदनशील कार्रवाई से पहले।	PROCESS_STATE_CREATEDPROCESS_STATE_FINISHEDPROCESS_STATE_FAILED	APIWeb

clientId, correlationId और credential हर फ़्लो में समान हैं।

अनुरोध

{
  "flow": "api+humantoken",
  "clientId": "client-a",
  "correlationId": "onboarding-001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document-number>" },
  "imageBase64": "<base64 selfie>"
}

सामान्य फ़ील्ड

फ़ील्ड	आवश्यक	सीमा (बाइट)	टिप्पणियाँ
flow	हाँ	64	फ़्लो में से एक
clientId	हाँ	128	क्लाइंट के लिए आपका id। इंटेलिजेंस अलग-अलग मानों की गणना करती है
correlationId	हाँ	128	इस प्रोसेस के लिए आपका संदर्भ। अद्वितीय: जो किसी अन्य प्रोसेस के पास पहले से है, उसकी स्थिति चाहे जो हो, 409 के साथ अस्वीकार किया जाता है
credential	हाँ, लेकिन खाली हो सकता है		की मौजूद होनी चाहिए। नीचे देखें
credential.type	दस्तावेज़ के साथ		एट्रिब्यूट कैटलॉग का एक कोड, सटीक और केस-सेंसिटिव
credential.value	दस्तावेज़ के साथ	64	दस्तावेज़ संख्या

flow, clientId और correlationId स्ट्रिंग होने चाहिए, बिना कंट्रोल कैरेक्टर और बिना शुरुआती या अंतिम व्हाइटस्पेस के। अमान्य मान अस्वीकार किए जाते हैं, कभी बदले नहीं जाते।

credential फ़ील्ड

• दस्तावेज़ के साथ: ठीक type और value वाला ऑब्जेक्ट, दोनों स्ट्रिंग, एक साथ भेजे गए।
• दस्तावेज़ के बिना: null या {}। प्रोसेस फिर भी इंटेलिजेंस में एक ट्रांज़ैक्शन और एक क्लाइंट के रूप में गिना जाता है।
• छोड़ा गया, या खाली स्ट्रिंग वाला ऑब्जेक्ट: 400 MISSING_CREDENTIAL_TYPE के साथ अस्वीकृत। इससे कुछ भी प्रोसेस होने से पहले गलत वर्तनी वाली की पकड़ में आ जाती है।
• credential के अंदर कोई भी अन्य की अस्वीकार की जाती है।

फ़्लो फ़ील्ड

प्रत्येक फ़्लो सामान्य फ़ील्ड में क्या जोड़ता है:

फ़ील्ड	फ़्लो	आवश्यक	मान
imageBase64	api+humantoken	हाँ	base64 में सेल्फ़ी। PNG, JPEG या WebP, अधिकतम 800 KB
callbackUri	humantoken, humantoken+revalidation	हाँ	कैप्चर समाप्त होने पर व्यक्ति जहाँ लौटता है: आपका कोई पेज, या आपके ऐप की URL स्कीम
references	humantoken+revalidation	हाँ	आपके अपेक्षित Human Token वाला एक आइटम, जैसा ऊपर के उदाहरण में है

Human Plugin इन फ़ील्ड को संग्रहीत नहीं करता, और गलत वर्तनी वाला वैकल्पिक फ़ील्ड बिना त्रुटि के अनदेखा किया जा सकता है।

api+humantoken के साथ एक चेहरे की सामने से ली गई, अच्छी रोशनी वाली सेल्फ़ी का उपयोग करें। जो मान इमेज नहीं है वह अस्वीकार कर दिया जाता है, और प्रोसेस विफल के रूप में संग्रहीत होता है: फ़्लो अस्वीकृतियाँ देखें।

humantoken+revalidation के साथ, परिणाम में humanToken की जगह humanTokenMatch होता है:

• "true": वह वही व्यक्ति है। प्रोसेस उस व्यक्ति के लिए गिना जाता है, और ndocs उसका वर्णन करता है।
• इसके अलावा कुछ भी, या ऐसा कैप्चर जो लाइव नहीं है: पुष्टि नहीं हुई। प्रोसेस किसी के लिए नहीं गिना जाता, और कोई ndocs नहीं होता।

दोनों मामलों में PROCESS_STATE_FINISHED लौटता है: humanTokenMatch पढ़ें। प्रोसेस प्राप्त करें देखें।

कुछ नाम Human Plugin द्वारा आरक्षित हैं और 400 INVALID_REQUEST के साथ अस्वीकार किए जाते हैं, जैसे clientReference। Human Plugin के अपने फ़ील्ड की कोई अन्य वर्तनी भी, जैसे client_id, correlation_id या Flow: केवल flow, clientId, correlationId और credential पढ़े जाते हैं, ठीक इसी वर्तनी में।

बॉडी नियम

• एक JSON ऑब्जेक्ट, अधिकतम 2 MiB (base64 में एक सेल्फ़ी के लिए लगभग पर्याप्त)। इससे बड़ी बॉडी 400 REQUEST_TOO_LARGE के साथ अस्वीकार की जाती है।
• JSON ऑब्जेक्ट के बाद कुछ भी नहीं आना चाहिए।

प्रतिक्रिया

201 Created, साथ में Location: /v1/processes/<id>.

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 2,
      "transactionsCount": 3,
      "firstSeen": "2026-09-08",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}

• id Human Plugin का UUID है। हर स्वीकृत अनुरोध एक नया बनाता है।
• state स्थानीय स्थिति है। जीवनचक्र देखें।
• humantoken और humantoken+revalidation एक token और एक link के साथ PROCESS_STATE_CREATED लौटाते हैं। ये एक बार लौटाए जाते हैं और कभी संग्रहीत नहीं होते: इन्हें सँभालकर रखें। Human Token Journey और अपने प्लेटफ़ॉर्म की कैप्चर गाइड देखें।
• data.ndocs व्यक्ति की इंटेलिजेंस है। यह अनुपस्थित हो सकती है: इंटेलिजेंस देखें।

data में परिणाम

समाप्त प्रोसेस के data में ये फ़ील्ड होते हैं। Journey फ़्लो इन्हें तब लौटाते हैं जब आप कैप्चर के बाद प्रोसेस पढ़ते हैं।

फ़ील्ड	कब	मान
humanToken	api+humantoken, humantoken	व्यक्ति कौन है: value Human Token है, और status validated होता है जब वह बनाया गया हो
humanTokenMatch	humantoken+revalidation	"true" जब वह references के Human Token वाला ही व्यक्ति हो
liveness	लाइवनेस जाँचने वाले फ़्लो, जैसे Journey फ़्लो	value live होता है जब कैप्चर किसी जीवित व्यक्ति से आया हो, या not_live जब नहीं आया हो; status validated होता है जब जाँच चली हो
ndocs	जब व्यक्ति के लिए इंटेलिजेंस उपलब्ध हो	व्यक्ति की इंटेलिजेंस

Journey परिणाम ऐसा दिखता है:

{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "liveness": { "value": "live", "status": "validated" },
    "ndocs": { "distinctClientsCount": 1, "transactionsCount": 1, "firstSeen": "2026-11-05", "lastSeen": "2026-11-05", "credentials": [] }
  }
}

परिणाम पर भरोसा करने से पहले liveness जाँचें: not_live होने पर कैप्चर को विफल मानें और व्यक्ति से फिर प्रयास करने को कहें। not_live वाला प्रोसेस किसी की इंटेलिजेंस में नहीं गिना जाता।

त्रुटियाँ

स्टेटस	message	अर्थ
400	INVALID_REQUEST, REQUEST_TOO_LARGE	एक JSON ऑब्जेक्ट नहीं है, आरक्षित फ़ील्ड, गलत टाइप, या 2 MiB से बड़ी बॉडी
400	MISSING_<FIELD>, INVALID_<FIELD>	कोई आवश्यक फ़ील्ड अनुपस्थित या गलत फ़ॉर्मेट में है, जैसे MISSING_CLIENT_ID
401	खाली ("")	Unico ने आपकी एक्सेस की अस्वीकार की: वह अनुपस्थित है, गलत है या अब वैध नहीं है। प्रोसेस विफल के रूप में संग्रहीत है। HUMAN_API_ACCESS_KEY जाँचें
409	CORRELATION_ID_ALREADY_USED	किसी अन्य प्रोसेस के पास पहले से यह correlationId है। कुछ भी संग्रहीत या भेजा नहीं गया
422	ATTRIBUTE_TYPE_NOT_SUPPORTED	credential.type कैटलॉग में नहीं है। कुछ भी संग्रहीत या भेजा नहीं गया
4xx	फ़्लो का message	फ़्लो ने अनुरोध अस्वीकार किया, उदाहरण के लिए अमान्य इमेज। फ़्लो अस्वीकृतियाँ देखें
502	UPSTREAM_UNAVAILABLE	प्रोसेस की समय पर पुष्टि नहीं हो सकी
503	DATABASE_UNAVAILABLE	डेटाबेस विफल रहा। कुछ भी प्रोसेस नहीं हुआ
500	INTERNAL	अप्रत्याशित त्रुटि

फ़्लो अस्वीकृतियाँ

जब कोई फ़्लो अनुरोध अस्वीकार करता है, तो create सामान्य एनवेलप में कारण को message में रखकर 4xx लौटाता है। सबसे आम:

message	कारण
invalid flow	flow आपके खाते के लिए सक्षम फ़्लो नहीं है
INVALID_IMAGE (400)	imageBase64 के बिना api+humantoken
INVALID_REQUEST (400)	imageBase64 base64 में इमेज नहीं है
IMAGE_TOO_LARGE	इमेज 800 KB से बड़ी है
UNSUPPORTED_IMAGE_FORMAT	इमेज PNG, JPEG या WebP नहीं है
PERMISSION_DENIED (403)	आपकी एक्सेस की इस फ़्लो के लिए सक्षम नहीं है

अस्वीकृत प्रोसेस विफल के रूप में संग्रहीत होता है। अनुरोध ठीक करें और नए correlationId के साथ नया प्रोसेस बनाएँ।

रीट्राई लॉजिक जोड़ने से पहले त्रुटियाँ और रीट्राई पढ़ें: नए प्रयास के लिए नया correlationId चाहिए।

आगे

प्रोसेस प्राप्त करें