Verification

Synchronously

curl -X POST https://api.randaverify.com/v2/verify/nin \
  -H "Authorization: Bearer rv_live_..." \
  -H "Idempotency-Key: signup-48219-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"nin": "22222222222", "reason": "corporate"}'

Requires the verify:nin scope. reason must be a key from GET /v1/nimc-reasons, not a label: the registry bills us for an invalid purpose code, so we check it before asking.

A registry round trip is typically 1 to 3 seconds. If you cannot hold a connection open for that, use the asynchronous flow below.

Asynchronously

curl -X POST https://api.randaverify.com/v2/verify/nin/async \
  -H "Authorization: Bearer rv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"nin": "22222222222", "reason": "corporate"}'

{
  "reference": "REF-AB58AB785AD4",
  "status": "queued",
  "environment": "live",
  "poll": "/v2/verify/REF-AB58AB785AD4"
}

You get 202 and a reference immediately. The result is delivered to every webhook endpoint you have registered for that environment, and is also readable at GET /v2/verify/{reference} whenever you like.

A reference means something straight away

The job is recorded before any work starts, so a reference you hold can always be asked about, even if it has not run yet. status moves from queued to running to done or failed.

The unit is taken when the registry is actually called, not when you submit, so a submission that never runs never costs anything.

What you get back

Which fields arrive depends on the field groups your organisation holds. The default is identity, and GET /v2/fields shows yours alongside every group that exists.

Group	Contains
identity (default)	Names, date of birth, gender, NIN, transaction id
contact	Phone number
address	Residential address, town, state
photograph	The portrait
origin	State and LGA of origin
maiden_name	Maiden name

A field you do not hold is absent, not empty, and the same filter applies to webhook payloads and to polled results. Ask us to widen your groups and we will, if your use case supports it: fewer fields is the default because asking for a photograph you do not need is a liability for both of us.

Retrying safely

Send Idempotency-Key on every verification. If the connection drops after we charged you, your retry with the same key returns the first answer instead of charging again.

• Same key, same request, already finished: the first response, with Idempotent-Replay: true.
• Same key while the first is still running: 409, idempotency_in_flight. Retry shortly without changing anything.
• Same key, different request body: 422. That is a bug in your client, and returning the first answer would hide it.

Keys last 24 hours. Use something from your own domain, such as your signup attempt id.

Charging

One unit per verification the registry completes and bills us for, including a negative answer: a “no match” is a question asked and answered, and the registry charges us for it. An outage, a timeout or a network failure is never charged. Sandbox calls are never charged.