Skip to content
Randaframes RandaVerify API

Getting started

This page walks you from zero to a successful verification in five steps. You should be done in under ten minutes.

Prerequisites

Section titled “Prerequisites”
  • A Self-Hosted tenant org provisioned by RandaVerify Operations.
  • The admin username and one-time password delivered to your business email.
  • Units credited to your org wallet (otherwise every verification request will return 402 Insufficient units).

If you do not yet have an org, contact onboarding — see Support.

Base URL

Section titled “Base URL”
EnvironmentBase URL
Productionhttps://api.randaverify.com

A staging environment is available on request — reach out to support.

Walk-through

Section titled “Walk-through”

  1. Activate your account.

    On first login you will be required to change your password. Hit POST /login once with your temporary credentials, change the password via POST /change-password, then re-login to get a fresh long-lived token. See Authentication for the full flow.

  2. Pick a verification reason.

    NIMC requires every verification to declare a reason (telecommunicationSimReg, nyscCheck, corporate, etc.). Fetch the current allowed list:

    Terminal window
    curl https://api.randaverify.com/nimc-reasons \
      -H "Authorization: Bearer $TOKEN"

    Use the key field as the reason value when calling a verification endpoint. The label field is for display purposes only.

  3. Run your first verification.

    Terminal window
    curl -X POST https://api.randaverify.com/verify-nin \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "nin": "12345678901",
        "reason": "corporate"
      }'

  4. Inspect the response.

    {
      "data": {
        "transaction_id": "430542871707201461583",
        "reference_id": "REF-1A2B3C4D5E6F",
        "nin": "12345678901",
        "tracking_id": "...",
        "fname": "JANE",
        "mname": "M",
        "lname": "DOE",
        "dob": "01-01-1990",
        "phone": "08012345678",
        "gender": "Female",
        "residenceAdress": "1 Test Road",
        "residenceTown": "Ikeja",
        "residenceLga": "Ikeja",
        "residenceState": "Lagos",
        "stateOfOrigin": "Lagos",
        "lgaOfOrigin": "Lagos Mainland",
        "image": "<base64 jpeg>"
      }
    }

    The same shape is used by every successful verification regardless of mode.

  5. Store the reference_id.

    The reference_id is your handle for this verification across our system. Persist it. You can re-fetch the same record any time using POST /verify-nin/requery — no unit is charged for a re-query.

Next steps

Section titled “Next steps”