reference · v1

VerifyHub API documentation

Verify NIN, BVN, and TIN records programmatically. Every response is JSON, every request is billed to your existing VerifyHub wallet, and every call is logged so you can see exactly what ran and when.

https://verifyhub.name.ng/api/v1

Before you start

You'll need an API key. Generate one from your dashboard — it's free to create, and billing only happens per successful request, drawn from the same wallet balance you already top up on the website.

Response shape

Every endpoint, success or failure, returns the same three fields:

{
  "success": true,
  "message": "NIN verified successfully",
  "data": { /* endpoint-specific payload, or null on failure */ }
}

Authentication

Every request needs a Bearer token in the Authorization header.

Authorization: Bearer vh_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

⚠️

Keep this key server-side. Anyone holding it can spend your wallet balance. If a key leaks, revoke it from your dashboard and generate a new one immediately.

Rate limits

Each key defaults to 60 requests per minute and 5,000 per day. Going over either returns 429. Need a higher limit for production traffic? Reach out from your dashboard.

Errors

The HTTP status code always tells you what happened — check it before reading data.

Status	Meaning
`400`	A required field is missing or malformed.
`401`	Your API key is missing, invalid, or has been revoked.
`402`	Your wallet balance can't cover this request's cost.
`422`	The request was valid, but the lookup itself failed — e.g. no matching record.
`429`	You've hit your per-minute or per-day rate limit.
`502` / `503`	The upstream verification service is unavailable. Retry with backoff.

NIN

Look up a National Identification Number.

POST /nin/verify from ₦500

Standard NIN lookup. Charged only on a successful match.

Request body

curl -X POST https://verifyhub.name.ng/api/v1/nin/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"nin": "12345678901"}'

Field	Type	Required
`nin`	string, 11 digits	Yes

POST /nin/verify-v1 from ₦500

Legacy lookup path, kept for backward compatibility. Unlike /nin/verify, this charges your wallet even when the NIN isn't found — only use it if you specifically need this behavior.

Request body

{ "nin": "12345678901" }

POST /nin/demo from ₦500

Find a NIN using demographic details instead of the number itself.

Request body

{
  "firstName": "Jane",
  "lastName": "Doe",
  "gender": "F",
  "dateOfBirth": "1995-06-20"
}

Field	Type	Required
`firstName`	string	Yes
`lastName`	string	Yes
`gender`	`"M"` or `"F"`	Yes
`dateOfBirth`	string, `YYYY-MM-DD`	Yes

POST /nin/phone from ₦500

Find a NIN using a registered Nigerian phone number.

Request body

{ "phone": "08012345678" }

POST /nin/validation from ₦300

Confirm that a NIN matches a specific BVN, phone number, or address on file. Call Validation types first to get a valid validation_type_id.

Request body

{
  "nin": "12345678901",
  "validation_type_id": 1,
  "match_value": "22222222222"
}

ℹ️

match_value is required whenever the chosen type has a field_code — it's the BVN, phone, or address you're checking against the NIN.

POST /nin/ipe from ₦600

Submit an IPE (identity postponement enrolment) clearance request using a tracking ID.

Request body

{ "tracking_id": "TRACK123456" }

GET /validation-types free

Lists the types available for NIN validation — each one includes the id and field_code you'll need for that call.

curl https://verifyhub.name.ng/api/v1/validation-types \
  -H "Authorization: Bearer YOUR_API_KEY"

BVN & TIN

Verify a Bank Verification Number or Tax Identification Number.

POST /bvn/verify from ₦70

Request body

curl -X POST https://verifyhub.name.ng/api/v1/bvn/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bvn": "22222222222"}'

Field	Type	Required
`bvn`	string, 11 digits	Yes

POST /tin from ₦80

Request body

{ "tin": "12345678-0001" }

Account

Check your balance and see what your key has been used for — neither of these costs anything to call.

GET /wallet/balance free

curl https://verifyhub.name.ng/api/v1/wallet/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /usage/logs free

Paginated history of every call made with your keys.

Query parameters

Field	Type	Default
`page`	integer	`1`
`per_page`	integer, max 100	`20`

curl "https://verifyhub.name.ng/api/v1/usage/logs?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"