Getting started

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

How Self-Hosted works

You deploy our open-source Self-Hosted portal (randaveriapi) on your own infrastructure. It exposes a stable /api/* surface to your frontend and proxies calls to RandaVerify’s hosted API at api.randaverify.com. The hosted API holds wallet balances, audit logs, and NIMC integration; the portal you run is a thin layer that holds tokens and shapes responses for your UI.

 your browser ──► your portal (randaveriapi) ──► api.randaverify.com ──► NIMC
                  on your infrastructure          RandaVerify hosted     upstream

This page walks through integrating against api.randaverify.com directly — useful for SDK authors and backend integrators. If you want a turnkey UI on top, use randaveriapi instead; its README has its own install steps.

Prerequisites

Account

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).
The Self-Hosted portal (randaveriapi) deployed on your own infrastructure if you’re using our reference frontend.

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

Compliance documents

Before we provision your Self-Hosted org we require the following from your business as part of standard KYB:

CAC (Corporate Affairs Commission) certificate — your business’s CAC registration document confirming you are a duly incorporated entity in Nigeria.
NDPR (Nigeria Data Protection Regulation) compliance certificate — current-year NDPR audit/compliance certificate evidencing your data-handling practices meet Nigerian privacy law.

Submit both PDFs to onboarding via the channel listed in Support. Provisioning typically completes within 24h of receipt.

Self-Hosted portal install

Self-Hosted customers run the open-source randaveriapi portal on their own server. The README in that repo has the full Python + (optional) React install steps; the short version:

git clone https://github.com/kittyrandaframes/randaveriapi
cd randaveriapi
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # defaults already point at api.randaverify.com
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

End-to-end install + first verification is usually under an hour. The portal does not hold any state of its own — wallet, users, and verifications all live on api.randaverify.com.

Base URL

The RandaVerify API runs at a single base URL:

https://api.randaverify.com/v1

There is no separate staging URL. Instead, the same endpoints support test mode for integration work: a small set of fixture NINs that short-circuit upstream NIMC, return deterministic mock data (or a deterministic 404), and consume zero units. You integrate, smoke-test, and dry-run against the same URL you’ll use in production — just with fixture NIN values during testing and real NINs when you go live.

See Testing with fixture NINs for the catalogue of fixture values and what each one tests.

Walk-through

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.
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/v1/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.

Run your first verification.

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

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.

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.