Run a verification

POST /v1/{scope}

Runs the scope named in the path and returns the verification. The request body is that scope’s inputs, sent directly as JSON.

Path parameters

string

required

The scope to run, for example nin, bvn, or face_match. The scope must be active for your organization and allowed by your key. See Scopes and activation.

Body

The body is the scope’s inputs. There is no wrapper object; the fields you send are the fields the scope expects. For a NIN lookup:

string

required

The 11 digit NIN to look up.

Each scope defines its own inputs. The fields above are for nin; see the scope’s page under Verification scopes for the inputs it takes.

Request

curl https://api.pruva.africa/v1/nin \
  -X POST \
  -H "X-Pruva-Key: pruva_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nin": "12345678901" }'

const res = await fetch("https://api.pruva.africa/v1/nin", {
  method: "POST",
  headers: {
    "X-Pruva-Key": "pruva_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ nin: "12345678901" }),
});

const verification = await res.json();

import requests

res = requests.post(
    "https://api.pruva.africa/v1/nin",
    headers={"X-Pruva-Key": "pruva_live_YOUR_KEY"},
    json={"nin": "12345678901"},
)

verification = res.json()

Response

Returns 201 with the verification in data.

{
  "status": true,
  "data": {
    "reference": "43817179a3dc8c341d358432b0590924",
    "scope": "nin",
    "category": "kyc",
    "countryCode": "NG",
    "status": "found",
    "request": { "nin": "12345678901" },
    "result": {
      "firstName": "Ada",
      "lastName": "Okafor",
      "dateOfBirth": "1990-04-12"
    },
    "errorMessage": null,
    "priceKobo": 5000,
    "charged": true,
    "createdAt": "2026-07-27T08:50:00+01:00"
  }
}

Response fields

string

Unique id for this verification. Use it to retrieve the result later.

string

The scope that ran.

string

found, not_found, or failed. See the three outcomes.

object

The details found, shaped by the scope. {} when nothing was found.

integer

What the check cost, in kobo.

boolean

Whether your wallet was debited.

string

When the check ran, ISO 8601.

Billing

A found or not_found result is charged; a failed result is not. The wallet is checked against the scope’s price before the provider is called. See Wallet and billing.

Errors

Code	When
`402`	Wallet balance too low. `error.details` carries the `reference`, `priceKobo`, and `balanceKobo`.
`403`	Scope not active for your organization, or not allowed by your key.
`403`	Organization not approved or suspended.
`422`	Missing or invalid inputs, or no scope in the path.
`502`	The provider could not complete the check. Not charged. `error.details` carries the `reference`.

See Errors for the full list and the error shape.

​Path parameters

​Body

​Request

​Response

​Response fields

​Billing

​Errors

Path parameters

Body

Request

Response

Response fields

Billing

Errors