ID-first pre-check: registry record by type + number (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 | — |
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" |
curl -X POST "$MONICHEK_API/verify/sessions/{id}:lookup-identity" \
-H "Authorization: Bearer $MONICHEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"id_type": "bvn",
"id_number": "string",
"name": "Ada Okafor",
"first_name": "Ada",
"last_name": "Okafor",
"dob": "2026-10-23",
"company_type": "RC",
"country": "NG"
}'const res = await fetch(`${MONICHEK_API}/verify/sessions/{id}:lookup-identity`, {
method: "POST",
headers: {
Authorization: `Bearer ${MONICHEK_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"id_type": "bvn",
"id_number": "string",
"name": "Ada Okafor",
"first_name": "Ada",
"last_name": "Okafor",
"dob": "2026-10-23",
"company_type": "RC",
"country": "NG"
}),
});
const data = await res.json();import os
import requests
res = requests.post(
f"{os.environ['MONICHEK_API']}/verify/sessions/{id}:lookup-identity",
headers={"Authorization": f"Bearer {os.environ['MONICHEK_API_KEY']}"},
json={
"id_type": "bvn",
"id_number": "string",
"name": "Ada Okafor",
"first_name": "Ada",
"last_name": "Okafor",
"dob": "2026-10-23",
"company_type": "RC",
"country": "NG"
},
)
print(res.json())$ch = curl_init(getenv('MONICHEK_API') . '/verify/sessions/{id}:lookup-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',
'name' => 'Ada Okafor',
'first_name' => 'Ada',
'last_name' => 'Okafor',
'dob' => '2026-10-23',
'company_type' => 'RC',
'country' => 'NG',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;Replace {id} with the resource id.
Responses
200 OK
registry record for confirmation (nothing persisted)
application/json
{
"object": "verify_identity_lookup",
"session_id": "vs_01M3R...",
"match": "full",
"score": 0.99,
"id_type": "bvn",
"id_number_last4": "1111",
"provider": "mock",
"latency_ms": 1,
"registry_data": {
"provider": "mock",
"id_type": "bvn",
"registry": "sandbox-registry",
"name_on_record": "Ada Obi",
"dob": "1990-05-17",
"nationality": "NG",
"gender": "F",
"status": "registry_match",
"checked_at": "2026-10-07T12:00:00Z"
}
}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.