Hosted identity step: run IDV and auto-screen (X-Verify-Token)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string | Yes | — |
Request
Content type: application/json · required
| Field | Type | Required | Description |
|---|---|---|---|
id_type |
string | Yes | one of bvn, nin, passport, drivers_licence, voters_card, cac |
id_number |
string | Yes | — |
names |
array of string | No | — |
full_name |
string | No | — |
first_name |
string | No | — |
last_name |
string | No | — |
dob |
string (date) | No | — |
company_type |
string | No | one of RC, BN, IT, LP, LLP |
country |
string | No | default "NG" |
image |
string | No | Base64 or data:image selfie. Max 2 MB decoded; never persisted. |
face_image |
string | No | Alias for image |
selfie |
string | No | Alias for image |
curl -X POST "$MONICHEK_API/verify/sessions/{id}:submit-identity" \
-H "Authorization: Bearer $MONICHEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"id_type": "bvn",
"id_number": "string",
"names": [
{
"full": "Ada Okafor"
}
],
"full_name": "Ada Okafor",
"first_name": "Ada",
"last_name": "Okafor",
"dob": "2026-10-23",
"company_type": "RC",
"country": "NG",
"image": "string",
"face_image": "string",
"selfie": "string"
}'const res = await fetch(`${MONICHEK_API}/verify/sessions/{id}:submit-identity`, {
method: "POST",
headers: {
Authorization: `Bearer ${MONICHEK_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"id_type": "bvn",
"id_number": "string",
"names": [
{
"full": "Ada Okafor"
}
],
"full_name": "Ada Okafor",
"first_name": "Ada",
"last_name": "Okafor",
"dob": "2026-10-23",
"company_type": "RC",
"country": "NG",
"image": "string",
"face_image": "string",
"selfie": "string"
}),
});
const data = await res.json();import os
import requests
res = requests.post(
f"{os.environ['MONICHEK_API']}/verify/sessions/{id}:submit-identity",
headers={"Authorization": f"Bearer {os.environ['MONICHEK_API_KEY']}"},
json={
"id_type": "bvn",
"id_number": "string",
"names": [
{
"full": "Ada Okafor"
}
],
"full_name": "Ada Okafor",
"first_name": "Ada",
"last_name": "Okafor",
"dob": "2026-10-23",
"company_type": "RC",
"country": "NG",
"image": "string",
"face_image": "string",
"selfie": "string"
},
)
print(res.json())$ch = curl_init(getenv('MONICHEK_API') . '/verify/sessions/{id}:submit-identity');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('MONICHEK_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'id_type' => 'bvn',
'id_number' => 'string',
'names' => [
[
'full' => 'Ada Okafor',
],
],
'full_name' => 'Ada Okafor',
'first_name' => 'Ada',
'last_name' => 'Okafor',
'dob' => '2026-10-23',
'company_type' => 'RC',
'country' => 'NG',
'image' => 'string',
'face_image' => 'string',
'selfie' => 'string',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Replace {id} with the resource id.
Responses
200 OK
identity_ok with idv/screening/combined verdicts
application/json
{
"object": "verify_session",
"session_id": "vs_01M3R...",
"status": "identity_ok",
"idv": {
"verification_id": "idv_01M3R...",
"score": 0.86,
"decision": "verified",
"reason": "match: Name and document number match the issuing registry."
},
"screening_id": "scr_01M3R...",
"screening_decision": "clear",
"combined_decision": "approved",
"risk_rating": "low",
"reasons": [
{
"code": "bundle.approved",
"detail": "Identity verified and screening clear."
}
],
"next_step": "acknowledge"
}Error responses
| Status | Meaning | Body |
|---|---|---|
| 401 | Unauthorized | RFC 9457 problem |
| 409 | Conflict | RFC 9457 problem |
| 422 | Unprocessable Entity | RFC 9457 problem |
| 502 | Bad Gateway | RFC 9457 problem |
Errors use the RFC 9457 problem format with a stable code.