Identity (KYC)

Verify a BVN or NIN and read past verifications.

Contents

Verifying an identity

Radok can check a Nigerian BVN or NIN against the national record and return the name it resolves to. Use it to confirm that the person opening an account, or the person you are about to pay, is who they say they are.

Results are cached

A repeat check of the same identifier is served from cache and is not charged again. You do not need to build your own cache on top — but you also should not treat a fast response as evidence that nothing was verified.

Verify a BVN

POST/v1/kyc/bvn

Auth: Secret key
Scope: kyc:write

Body

Field	Type	Description
bvnrequired	string	Exactly 11 digits.
phonerequired	string	At least 10 characters. The phone number to check against the record.

curl

curl -X POST https://api.radokpay.com/v1/kyc/bvn \
  -H "Authorization: Bearer $RADOK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "bvn": "22123456789", "phone": "08031234567" }'

200 OK

{
  "data": {
    "reference": "kyc_7d2a9f4c1b8e3506",
    "verified": true,
    "name": "ADA LOVELACE",
    "cacheHit": false
  }
}

Response

Field	Type	Description
reference	string	The verification record, for your audit trail.
verified	boolean	Whether the identity matched. A `200` with `verified: false` is a successful check with a negative answer — not an error.
name	string	The name on record when the provider returned one. Use `verified` to decide the outcome — do not infer it from whether `name` is set.
cacheHit	boolean	True when served from cache rather than re-checked.

Check the field, not the status code

The most common mistake here is treating 200 as “verified”. The request succeeded; whether the identity matched is data.verified.

Verify a NIN

POST/v1/kyc/nin

Auth: Secret key
Scope: kyc:write

Identical to the BVN endpoint, with nin in place of bvn. Also exactly 11 digits.

curl

curl -X POST https://api.radokpay.com/v1/kyc/nin \
  -H "Authorization: Bearer $RADOK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nin": "12345678901", "phone": "08031234567" }'

List past verifications

GET/v1/kyc/requests

Auth: Secret key
Scope: kyc:read

Query

Field	Type	Description
limit	integer	1–100. Defaults to 20.
cursor	string	From `meta.nextCursor`.

curl

curl "https://api.radokpay.com/v1/kyc/requests?limit=20" \
  -H "Authorization: Bearer $RADOK_SECRET_KEY"

Rows carry the reference, type, status, and verified name. The fee charged is not returned.

Events

A match emits kyc.succeeded; a non-match emits kyc.failed.
Both are useful when verification is triggered from a background job rather than from a request a user is waiting on.

Handling identity data

Do not log a BVN or NIN. Store our reference instead — it is enough to reconstruct the audit trail without holding the identifier.
Collect these only where you have a legal basis to, and keep them no longer than that basis allows.
Verification is a secret-key operation. Do not embed a secret key in a browser or mobile app — identifiers must be checked from your server.