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

Hosted identity step: run IDV and auto-screen (X-Verify-Token)

Bearer API key or staff session application/json operation submitVerifyIdentity

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 —
names array of string No —
full_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"
image string No Base64 or data:image selfie. Max 2 MB decoded; never persisted.
face_image string No Alias for image
selfie string No Alias for image
curl -X POST "$MONICHEK_API/verify/sessions/{id}:submit-identity" \
  -H "Authorization: Bearer $MONICHEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "id_type": "bvn",
  "id_number": "string",
  "names": [
    {
      "full": "Ada Okafor"
    }
  ],
  "full_name": "Ada Okafor",
  "first_name": "Ada",
  "last_name": "Okafor",
  "dob": "2026-10-23",
  "company_type": "RC",
  "country": "NG",
  "image": "string",
  "face_image": "string",
  "selfie": "string"
}'
const res = await fetch(`${MONICHEK_API}/verify/sessions/{id}:submit-identity`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${MONICHEK_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "id_type": "bvn",
    "id_number": "string",
    "names": [
      {
        "full": "Ada Okafor"
      }
    ],
    "full_name": "Ada Okafor",
    "first_name": "Ada",
    "last_name": "Okafor",
    "dob": "2026-10-23",
    "company_type": "RC",
    "country": "NG",
    "image": "string",
    "face_image": "string",
    "selfie": "string"
  }),
});

const data = await res.json();
import os
import requests

res = requests.post(
    f"{os.environ['MONICHEK_API']}/verify/sessions/{id}:submit-identity",
    headers={"Authorization": f"Bearer {os.environ['MONICHEK_API_KEY']}"},
    json={
      "id_type": "bvn",
      "id_number": "string",
      "names": [
        {
          "full": "Ada Okafor"
        }
      ],
      "full_name": "Ada Okafor",
      "first_name": "Ada",
      "last_name": "Okafor",
      "dob": "2026-10-23",
      "company_type": "RC",
      "country": "NG",
      "image": "string",
      "face_image": "string",
      "selfie": "string"
    },
)
print(res.json())
$ch = curl_init(getenv('MONICHEK_API') . '/verify/sessions/{id}:submit-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',
        'names' => [
            [
                'full' => 'Ada Okafor',
            ],
        ],
        'full_name' => 'Ada Okafor',
        'first_name' => 'Ada',
        'last_name' => 'Okafor',
        'dob' => '2026-10-23',
        'company_type' => 'RC',
        'country' => 'NG',
        'image' => 'string',
        'face_image' => 'string',
        'selfie' => 'string',
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Replace {id} with the resource id.

Responses

200 OK identity_ok with idv/screening/combined verdicts application/json
{
  "object": "verify_session",
  "session_id": "vs_01M3R...",
  "status": "identity_ok",
  "idv": {
    "verification_id": "idv_01M3R...",
    "score": 0.86,
    "decision": "verified",
    "reason": "match: Name and document number match the issuing registry."
  },
  "screening_id": "scr_01M3R...",
  "screening_decision": "clear",
  "combined_decision": "approved",
  "risk_rating": "low",
  "reasons": [
    {
      "code": "bundle.approved",
      "detail": "Identity verified and screening clear."
    }
  ],
  "next_step": "acknowledge"
}

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.