API documentation

The Verity API is a JSON REST API over HTTPS. Every request is a POST with a JSON body; every response is JSON.

Each check needs the person’s consent. Send "consent": true only when the person has agreed to have their NIN or BVN verified, as required by the Nigeria Data Protection Act.

Authenticate with an API key from the Developers page of a verified Verity business account (create a business account, complete Business verification, then create a key), sent as a Bearer token:

Authorization: Bearer vng_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• vng_test_… keys run in test mode: fixed sample results, never charged.
• vng_live_… keys run real checks and charge your wallet.
• Keep keys on your server. Never put them in browser or mobile app code. Revoke a key immediately if it leaks.

Create a test key, then run this. It returns a sample result without charging anything.

curl -X POST https://verity.com.ng/api/v1/verify/nin \
  -H "Authorization: Bearer $VERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nin": "10000000001", "consent": true }'

POST /verify/nin. Looks up a National Identification Number.

curl -X POST https://verity.com.ng/api/v1/verify/nin \
  -H "Authorization: Bearer $VERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "nin": "12345678901", "consent": true }'

POST /verify/bvn. Looks up a Bank Verification Number.

curl -X POST https://verity.com.ng/api/v1/verify/bvn \
  -H "Authorization: Bearer $VERITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "bvn": "22222222222", "consent": true }'

A successful check returns 200:

{
  "status": "verified",
  "mode": "test",
  "type": "NIN",
  "reference": "test_5f1c9a0e2b7d43aa91c2",
  "charged": { "amount": 0, "currency": "NGN" },
  "data": {
    "idNumber": "10000000001",
    "firstName": "Ada",
    "middleName": "Test",
    "lastName": "Okafor",
    "fullName": "Ada Test Okafor",
    "dateOfBirth": "1994-03-12",
    "gender": "Female",
    "phone": "08000000000",
    "photo": null
  },
  "requestId": "req_5f1c9a0e2b7d43aa91c2e8f0"
}

Requests made with a test key never reach the identity provider and are never charged. Use these numbers:

Any other valid number returns 404 not_found in test mode. Validation, consent and authentication errors behave exactly as in live mode.

Live checks are paid from your Verity wallet, the same wallet as dashboard checks.

The fee is reserved when the check starts. If no record is found or the identity service fails, it’s refunded automatically. If your balance is too low the request fails with 402 insufficient_balance and nothing is charged.

Errors use standard HTTP status codes and a JSON body with a stable code you can branch on:

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your Verity wallet doesn't cover this check. Top up from the dashboard."
  },
  "requestId": "req_9b2e41d0c3a84f17b6aa0c51"
}

Each key can make 60 requests per minute. Over that you’ll get 429 rate_limited; wait a few seconds and retry. Need more? Email support@verity.com.ng.