string The unique business ID for the transaction that triggered this verification, such as an order ID. Must be non-empty and no longer than 99 characters.
userId
string The unique user ID for the user performing the verification. Must be non-empty and no longer than 200 characters.
string The identity number type. Case-sensitive — must be uppercase. See Supported numberType for the full list. Any value not in the supported set (or lowercase such as bvn / nin) will be rejected with PARAMETER_ERROR / Number type and country are not match.
numberValue
string The identity number value. Format depends on numberType. See Supported numberType.
Supported numberType
New identity number types are appended to this table. numberType must match the region column exactly (uppercase).
numberType
region
numberValue format
Description
BVN
NGA
11-digit numeric string
Nigeria Bank Verification Number
NIN
NGA
11-digit numeric string
Nigeria National Identity Number
Response Description
Parameter
Description
code
Response Code.
transactionId
The request ID of this API call. The max length is 64.
pricingStrategy
Deprecated, always returns FREE.
message
Status Code Explanation.
data
object The business result of the verification.
Response.data
Field
Description
signatureId
The business ID of this verification.
overallResult
Overall verification result. One of PASS or FAIL or INCOMPLETE.
errorCode
Business-level error code when overallResult is not PASS. Returns an empty string when overallResult is PASS. Possible values: NUMBER_NOT_EXIST, BVN_SUSPEND, INFO_ABNORMAL, INVALID_FORMAT, ERROR.
docDatabaseDetail
object The person information returned by the authoritative database.
Response.data.docDatabaseDetail
Field
Description
firstName
string Given name.
middleName
string Middle name. This field may be empty.
lastName
string Family name or surname.
gender
string Gender returned by the database, for example Male or Female.
birthday
string Date of birth, normalized to yyyy-MM-dd.
phoneNumber1
string Primary phone number.
phoneNumber2
string Secondary phone number. This field may be empty.
Response.code
This API returns two layers of status codes. The top-level code only reflects infrastructure-level or request-level failures. Business verification results, including invalid number format and vendor failures, are returned in data.overallResult and data.errorCode when the top-level code is SUCCESS.
Top-level code
Status Code
Message
SUCCESS
OK. The request reached business processing. The actual verification result is returned in data.overallResult and data.errorCode.
PARAMETER_ERROR
BizId is wrong (bizId is missing)
BizId is too long (bizId length exceeds 99)
UserId is invalid (userId is missing)
UserId is too long (userId length exceeds 200)
Region is wrong (missing or not a supported ISO ALPHA-3 code)
numberType is empty
numberType is wrong (length > 30 or not a supported type)
Number type and country are not match (numberType not in supported set for the region, or not uppercase)
Invalid ID number, please check the format (numberValue is empty, or fails format validation for the given numberType — e.g. BVN / NIN must be an 11-digit numeric string)
IAM_FAILED
IAM check failed
ERROR
Server error
data.errorCode
This section applies only when the top-level code is SUCCESS.
errorCode
overallResult
Description
""
PASS
Database lookup succeeded and returned a matching record.
INVALID_FORMAT
FAIL
numberValue failed format validation. For example, BVN and NIN must be 11 digits.
NUMBER_NOT_EXIST
FAIL
The identity number does not exist in the authoritative database.
BVN_SUSPEND
FAIL
The BVN is suspended.
INFO_ABNORMAL
FAIL
Information is abnormal on the authoritative database side. Retry later.
ERROR
INCOMPLETE
The vendor call failed or timed out, or numberType is not supported by this solution.
{
"code": "PARAMETER_ERROR",
"message": "BizId is wrong (bizId is missing)",
"data": null,
"extra": null,
"transactionId": "20278fe987234752",
"pricingStrategy": "FREE"
}
{
"code": "PARAMETER_ERROR",
"message": "BizId is too long (bizId length exceeds 99)",
"data": null,
"extra": null,
"transactionId": "20278fe987234752",
"pricingStrategy": "FREE"
}
{
"code": "PARAMETER_ERROR",
"message": "UserId is invalid (userId is missing)",
"data": null,
"extra": null,
"transactionId": "0efa02349b10bd2e",
"pricingStrategy": "FREE"
}
{
"code": "PARAMETER_ERROR",
"message": "UserId is too long (userId length exceeds 200)",
"data": null,
"extra": null,
"transactionId": "0efa02349b10bd2e",
"pricingStrategy": "FREE"
}
{
"code": "PARAMETER_ERROR",
"message": "Region is wrong (missing or not a supported ISO ALPHA-3 code)",
"data": null,
"extra": null,
"transactionId": "0f74aeb4dd3f1d48",
"pricingStrategy": "FREE"
}
{
"code": "PARAMETER_ERROR",
"message": "numberType is wrong (length > 30 or not a supported type)",
"data": null,
"extra": null,
"transactionId": "2ad35b5ef69fc8c4",
"pricingStrategy": "FREE"
}
{
"code": "PARAMETER_ERROR",
"message": "Number type and country are not match (numberType not in supported set for the region, or not uppercase)",
"data": null,
"extra": null,
"transactionId": "2ad35b5ef69fc8c4",
"pricingStrategy": "FREE"
}
{
"code": "PARAMETER_ERROR",
"message": "Invalid ID number, please check the format (numberValue is empty, or fails format validation for the given numberType — e.g. BVN / NIN must be an 11-digit numeric string)",
"data": null,
"extra": null,
"transactionId": "2ad35b5ef69fc8c4",
"pricingStrategy": "FREE"
}
