POST /lookup

One normalized registry lookup

Bearer API key or staff session application/json operation lookup

Request

Content type: application/json · required

Field	Type	Required	Description
`id_type`	string	Yes	one of `bvn`, `nin`, `cac`, `drivers_licence`, `passport`, `voters_card`, `postcode`
`id_number`	string	Yes	—
`name`	string	No	Full name; used to split first/last where a vendor requires it
`first_name`	string	No	—
`last_name`	string	No	—
`dob`	string (date)	No	Required for some passport/driver/voter checks
`company_type`	string	No	CAC registration type one of `RC`, `BN`, `IT`, `LP`, `LLP`
`country`	string	No	default `"NG"`
`customer_id`	string	No	—

curl -X POST "$MONICHEK_API/lookup" \
  -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",
  "customer_id": "cus_01M3R..."
}'

const res = await fetch(`${MONICHEK_API}/lookup`, {
  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",
    "customer_id": "cus_01M3R..."
  }),
});

const data = await res.json();

import os
import requests

res = requests.post(
    f"{os.environ['MONICHEK_API']}/lookup",
    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",
      "customer_id": "cus_01M3R..."
    },
)
print(res.json())

$ch = curl_init(getenv('MONICHEK_API') . '/lookup');
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',
        'customer_id' => 'cus_01M3R...',
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Responses

200 OK match grade with score and provider application/json

{
  "object": "lookup",
  "id": "lkp_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",
    "status": "registry_match",
    "checked_at": "2026-10-07T12:00:00Z"
  }
}

Error responses

Status	Meaning	Body
401	Unauthorized	RFC 9457 problem
422	Unprocessable Entity	RFC 9457 problem
429	Too Many Requests	RFC 9457 problem
502	Bad Gateway	RFC 9457 problem

Errors use the RFC 9457 problem format with a stable code.