API reference OpenAPI 3.1
POST /idv/verifications

Run one identity verification (optionally with a face image)

Bearer API key or staff session application/json operation createIdvVerification

Request

Content type: application/json · required

FieldTypeRequiredDescription
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

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