Run one identity verification (optionally with a face image)
Request
Content type: application/json · required
| Field | Type | Required | Description |
|---|---|---|---|
id_type |
string | Yes | one of bvn, nin, cac, drivers_licence, passport, voters_card |
id_number |
string | Yes | — |
customer_id |
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 URL. Max 2 MB decoded. Not persisted. |
face_image |
string | No | Alias for image |
liveness |
boolean | No | Require liveness. Without a face image a registry hit is returned as review, never verified. default true |
curl -X POST "$MONICHEK_API/idv/verifications" \
-H "Authorization: Bearer $MONICHEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"id_type": "bvn",
"id_number": "string",
"customer_id": "cus_01M3R...",
"first_name": "Ada",
"last_name": "Okafor",
"dob": "2026-10-23",
"company_type": "RC",
"country": "NG",
"image": "string",
"face_image": "string",
"liveness": true
}'const res = await fetch(`${MONICHEK_API}/idv/verifications`, {
method: "POST",
headers: {
Authorization: `Bearer ${MONICHEK_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"id_type": "bvn",
"id_number": "string",
"customer_id": "cus_01M3R...",
"first_name": "Ada",
"last_name": "Okafor",
"dob": "2026-10-23",
"company_type": "RC",
"country": "NG",
"image": "string",
"face_image": "string",
"liveness": true
}),
});
const data = await res.json();import os
import requests
res = requests.post(
f"{os.environ['MONICHEK_API']}/idv/verifications",
headers={"Authorization": f"Bearer {os.environ['MONICHEK_API_KEY']}"},
json={
"id_type": "bvn",
"id_number": "string",
"customer_id": "cus_01M3R...",
"first_name": "Ada",
"last_name": "Okafor",
"dob": "2026-10-23",
"company_type": "RC",
"country": "NG",
"image": "string",
"face_image": "string",
"liveness": true
},
)
print(res.json())$ch = curl_init(getenv('MONICHEK_API') . '/idv/verifications');
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',
'customer_id' => 'cus_01M3R...',
'first_name' => 'Ada',
'last_name' => 'Okafor',
'dob' => '2026-10-23',
'company_type' => 'RC',
'country' => 'NG',
'image' => 'string',
'face_image' => 'string',
'liveness' => true,
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Responses
201 Created
verification decision; raw base64 images are never returned or stored
application/json
{
"object": "idv_verification",
"id": "idv_01M3R...",
"provider": "prembly",
"id_type": "bvn",
"id_number_last4": "8924",
"status": "completed",
"decision": "verified",
"score": 0.99,
"reason": "face match",
"response": {
"provider": "prembly",
"face": {
"matched": true,
"confidence": 0.99,
"threshold": 90
},
"liveness": {
"checked": true,
"passed": true,
"score": 0.99
}
}
}Error responses
| Status | Meaning | Body |
|---|---|---|
| 401 | Unauthorized | 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.