Identity checks

Virtual NIN

Checks a virtual NIN: the 16-character token a person generates for your business, so you never handle their raw NIN.

POST/v1/kyc/vnin

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

vninstringrequired
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/vnin

curl -X POST https://api.verath.io/v1/kyc/vnin \
  -H "Authorization: Bearer $VERATH_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onb_cust_1042" \
  -d '{"vnin":"VT00000000000003","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": "vnin",
  "status": "completed",
  "found": true,
  "source": "registry",
  "source_ref": "sbx_8f29a712c4e01b5d",
  "id_number": null,
  "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.