Identity checks

NIN basic

Checks a National Identification Number and tells you whether the name, date of birth and gender you send match the record. The most common check for account opening.

POST/v1/kyc/nin/basic

Request

Authenticate with Authorization: Bearer <your key>. Send a JSON body.

Headers

Idempotency-Keystring
Repeats within 24 hours return the stored result, free.
X-Simulate-Outage"registry" | "all"
Test keys only: simulate a source outage.

Body

ninstringrequired
11 digits.
purpose"KYC-ONB" | "KYC-REV" | "LEND" | "EMPL"required
Why you are checking (recorded on every check).
first_namestring
Up to 100 characters.
middle_namestring
Up to 100 characters.
last_namestring
Up to 100 characters.
dobstring (date)
YYYY-MM-DD
phonestring
Up to 100 characters.
gender"male" | "female"
consent_refstring
Your reference for the person's consent.
customer_refstring
Your ID for the person. Links checks to one customer record.

Example

POST /v1/kyc/nin/basic

curl -X POST https://api.verath.io/v1/kyc/nin/basic \
  -H "Authorization: Bearer $VERATH_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onb_cust_1042" \
  -d '{"nin":"70000000006","first_name":"Ngozi","last_name":"Lagbaja","dob":"1994-05-14","purpose":"KYC-ONB","customer_ref":"cust_1042"}'

200 OK

{
  "reference_id": "chk_3c5e1f0a9b2d4c7e8f6a1b2c3d4e5f60",
  "object": "check",
  "check": "nin_basic",
  "status": "completed",
  "found": true,
  "source": "registry",
  "source_ref": "sbx_8f29a712c4e01b5d",
  "id_number": { "type": "nin", "last_digits": "0006" },
  "match": { "first_name": 100, "last_name": 100, "dob": 100 },
  "match_result": { "first_name": "match", "last_name": "match", "dob": "match" },
  "route": [{ "source": "registry", "outcome": "found", "latency_ms": 412, "ref": "sbx_8f29a712c4e01b5d" }],
  "latency_ms": 431,
  "error": null,
  "cost": { "billed": false, "amount_kobo": 0, "currency": "NGN" },
  "customer": { "id": "cus_9a7b…", "customer_ref": "cust_1042" },
  "purpose": "KYC-ONB",
  "consent_ref": null,
  "mode": "test",
  "created_at": "2026-11-11T15:32:00.112Z",
  "completed_at": "2026-11-11T15:32:00.543Z",
  "retry": null,
  "data": null,
  "data_policy": "match_only"
}

Responses

Status	Meaning
200	Completed: found or not found.
400	Invalid request.
401	Missing, invalid or revoked API key.
402	insufficient_funds or budget_exceeded.
403	capability_not_enabled, kyc_unavailable or pricing_not_set.
409	idempotency_conflict or idempotency_in_progress.
423	identity_locked: the owner locked this NIN or BVN on Verath (businesses that honour locks). Never billed.
424	upstream_unavailable: no source answered. The check is pending and retried for up to 72 hours (verification.completed / verification.failed). Never billed.
429	Rate limited. Honour Retry-After.