API reference OpenAPI 3.1
POST /verify/sessions/{id}:lookup-identity

ID-first pre-check: registry record by type + number (X-Verify-Token)

Bearer API key or staff session application/json operation lookupVerifyIdentity

Parameters

NameInTypeRequiredDescription
id path string Yes —

Request

Content type: application/json · required

FieldTypeRequiredDescription
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

StatusMeaningBody
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.