Skip to content
Randaframes RandaVerify by Randaframes

Getting started

The v2 API is for systems that embed identity verification into their own flows: a signup form, an onboarding queue, a KYC step. You authenticate with an API key rather than a username and password, and you can work entirely against a sandbox before anything costs a unit.

The whole integration in four steps

Section titled “The whole integration in four steps”

  1. Issue a sandbox key in your dashboard, under API keys. Choose the test environment and the scopes you need. The token is shown once: store it before you close the dialog.

  2. Make a verification against a fixture NIN. No registry call, no units.

    Terminal window
    curl -X POST https://api.randaverify.com/v2/verify/nin \
      -H "Authorization: Bearer rv_test_9f2a1c7b4e8d0a63_qp3F..." \
      -H "Content-Type: application/json" \
      -d '{"nin": "12345678901", "reason": "corporate"}'
    {
      "reference": "REF-24936810F850",
      "status": "verified",
      "environment": "test",
      "data": {
        "fname": "SUMAILA",
        "mname": "MEMUNAT",
        "lname": "AKOWE",
        "dob": "19 AUG 1989",
        "gender": "F",
        "nin": "12345678901"
      },
      "fields_granted": ["identity"]
    }

  3. Exercise the paths you will actually hit in production: a NIN the registry does not hold, a malformed NIN, an expired credential. GET /v2/sandbox/nins lists what the sandbox answers and what each one demonstrates.

  4. Issue a live key and change the string. Same endpoints, same shapes, same code. A rv_live_ key reserves a unit and asks the registry.

What the sandbox guarantees

Section titled “What the sandbox guarantees”

A rv_test_ key cannot reach the registry and cannot move units. That is enforced below the endpoints rather than inside them, so it holds for every endpoint we will ever add. Sandbox traffic is tagged and never appears in your usage or your invoice.

The sandbox returns a deliberately sparse record as well as a complete one (12345678902). Older NIN registrations really do come back without a phone number or a photograph, and an integration that has only ever seen the full record breaks the first time it meets a partial one. Test against both.

Before you go live

Section titled “Before you go live”
CheckWhy
You branch on error.code, never on error.messageMessages are reworded; codes are a promise
You only retry when error.retryable is trueRetrying an invalid NIN forever helps nobody
You send Idempotency-Key on verificationsA timeout and a retry must not charge you twice
You log X-Request-IdIt is the one thing support needs from you
You handle a sparse recordPartial bio is common in production

Where to look next

Section titled “Where to look next”