Identity checks

NIN premium

Everything in NIN basic. Businesses approved for records also get the record fields (including the photo) once, in data, when the source allows it. Everyone else gets match results only.

POST/v1/kyc/nin/premium

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/premium

curl -X POST https://api.verath.io/v1/kyc/nin/premium \
  -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_premium",
  "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.