Skip to navigation
API ReferenceIdentity and KYC

Verify BVN

Checks a BVN with the bank and returns the details on record. The answer is immediate.

Limited to 20 requests a minute and 2,000 a day for each API key. A validation failure answers 400 with the first error as the message.

Authentication

AuthorizationBearer

Your Halo partner API key, sent as Authorization: Bearer <key>.

Request

This endpoint expects an object.
bvnstringRequiredformat: "^[0-9]{11}$"

The 11-digit BVN.

customer_referencestring or nullOptional<=255 characters
Your own reference, echoed back. At most 255 characters.

Response

The BVN is valid.
statusboolean
True on success, false otherwise.
messagestring or map from strings to lists of strings
A short message. On a 422 validation failure it is an object of field names to error lists.
status_codeinteger
The HTTP status code.
dataanyOptional
The result. Left out on most errors.

Errors

400
Bad Request Error
401
Unauthorized Error
429
Too Many Requests Error
500
Internal Server Error