HMKVerify Developer API
Welcome to the HMKVerify Developer Hub. Our RESTful API enables you to integrate real-time Bank Verification Number (BVN) and National Identity Number (NIN) lookup capabilities directly into your internal databases, customer portals, or KYC workflows.
Key API Capabilities
-
✓
Bearer Token Security
Authorize requests cleanly by placing your secret key inside the HTTP headers.
-
✓
Transparent Gateway Fallbacks
If the active provider gateway lacks query support, HMKVerify automatically routes the request to CheckMyNIN behind the scenes, guaranteeing maximum uptime.
-
✓
Isolated API Billing
Administrators set separate billing rates for API users inside the pricing dashboard, allowing you to optimize payment control.
https://hmkverify.com
User Wallet Balance
Retrieve the current user profile metadata alongside their active prepaid balance. Authenticates using the user's secret Bearer API key.
Request Headers
| Header Name | Type | Required | Description |
|---|---|---|---|
| Authorization | String | Yes | Authentication bearer token payload in the format Bearer hk_live_... |
NIN Verification
Query and retrieve verified personal identity details using the user's 11-digit National Identity Number (NIN). Requires formal consent confirmation.
Request Body Parameters (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| verify_method | String | Yes | Must be set to exactly "nin" |
| identifier | String | Yes | The 11-digit NIN verification code |
| isConsent | Boolean | Yes | Must be true to execute checkout validation compliant under data privacy audit rules |
| slip_type | String | No | Choose between "regular" (default), "standard", or "premium" |
NIN Phone Lookup
Retrieve a user's NIN record using the phone number registered to their identity record. Falls back to CheckMyNIN.
Request Body Parameters (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| verify_method | String | Yes | Must be set to exactly "nin-phone" |
| identifier | String | Yes | The registered 11-digit phone number |
| isConsent | Boolean | Yes | Must be true to proceed |
| slip_type | String | No | Regular, standard, or premium options |
NIN Tracking ID Validation
Check and validate the status of a National Identity Number using its official transaction tracking reference ID.
Request Body Parameters (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| tracking_id | String | Yes | The tracking ID reference generated by NIMC enrollment centres |
| isConsent | Boolean | Yes | Must be true to proceed |
NIN Demographics Lookup
Perform lookup queries matching input fields (firstname, surname, dob, gender) against registry database records.
Request Body Parameters (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| firstname | String | Yes | First name matching search record |
| surname | String | Yes | Last/Surname matching search record |
| dob | Date | Yes | Date of Birth formatted as YYYY-MM-DD |
| gender | String | Yes | Must be one of "male", "female", "m", "f" |
| isConsent | Boolean | Yes | Must be true to proceed |
Purchase Exam Scratch Card PIN
Purchase WAEC, NECO, NABTEB, or NBAIS exam scratch card PINs programmatically. The system draws from local inventory first; if stock is insufficient, it fetches live PINs from the EasyAccess provider. The wallet is debited and the PINs are returned instantly.
Request Body Parameters (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| exam_board | String | Yes | One of "WAEC", "NECO", "NABTEB", "NBAIS" |
| quantity | Integer | Yes | Number of PINs to purchase. Between 1 and 50 |
BVN Verification
Verify Bank Verification Numbers (BVN) directly against registry databases to confirm enrollment details and bios.
Request Body Parameters (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| bvn | String | Yes | The 11-digit BVN lookup code |
| isConsent | Boolean | Yes | Must be true to proceed |
BVN Phone Retrieval
Retrieve a customer's registered bank profile BVN code using their primary phone number identifier.
Request Body Parameters (JSON)
| Field | Type | Required | Description |
|---|---|---|---|
| phone | String | Yes | The 11-digit registered phone number |
| isConsent | Boolean | Yes | Must be true to proceed |
# Include your secret token in the authorization header:
Authorization: Bearer YOUR_API_TOKEN
# Base URL for API requests:
https://hmkverify.com
curl --request GET \
--url https://hmkverify.com/api/v1/balance \
--header 'Authorization: Bearer YOUR_API_TOKEN'
curl --request POST \
--url https://hmkverify.com/api/v1/verify/nin \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"verify_method": "nin",
"identifier": "12345678901",
"isConsent": true,
"slip_type": "regular"
}'
curl --request POST \
--url https://hmkverify.com/api/v1/verify/nin-phone \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"verify_method": "nin-phone",
"identifier": "08012345678",
"isConsent": true,
"slip_type": "regular"
}'
curl --request POST \
--url https://hmkverify.com/api/v1/verify/nin-validation \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"tracking_id": "REF-987654321",
"isConsent": true
}'
curl --request POST \
--url https://hmkverify.com/api/v1/verify/nin-demographics \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"firstname": "SANI",
"surname": "IBRAHIM",
"dob": "1995-10-15",
"gender": "male",
"isConsent": true
}'
curl --request POST \
--url https://hmkverify.com/api/v1/verify/bvn \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"bvn": "22222222222",
"isConsent": true
}'
curl --request POST \
--url https://hmkverify.com/api/v1/verify/bvn-phone \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"phone": "08012345678",
"isConsent": true
}'
curl --request POST \
--url https://hmkverify.com/api/v1/purchase/exam-pin \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"exam_board": "WAEC",
"quantity": 2
}'
{
"status": "error",
"message": "Unauthorized. Please provide a valid Bearer API Token."
}
{
"status": "error",
"message": "Insufficient wallet balance. Please top up."
}
{
"status": "error",
"message": "Validation error.",
"errors": {
"identifier": [
"The identifier field is required."
],
"isConsent": [
"Consent confirmation is required."
]
}
}
{
"message": "Welcome to HMKVerify Developer API Documentation.",
"status": "online",
"version": "v1.0"
}
{
"status": "success",
"username": "developer_sani",
"email": "devsani@gmail.com",
"balance": 15000.00
}
{
"status": "success",
"data": {
"firstname": "SANI",
"surname": "IBRAHIM",
"middlename": "ALHASSAN",
"gender": "Male",
"birthdate": "1995-10-15",
"dob": "1995-10-15",
"telephoneno": "08012345678",
"phone": "08012345678",
"phoneNumber": "08012345678",
"state_of_origin": "Kano",
"residence_state": "Kano",
"residence_lga": "Nassarawa",
"residence_address": "123 Zoo Road, Nassarawa LGA, Kano State",
"lga_origin": "Nassarawa",
"photo": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"signature": "iVBORw0KGgoAAAANSUkhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
"nin": "12345678901",
"bvn": null,
"trackingId": "API_TXN_REF987654321",
"tracking_id": "API_TXN_REF987654321"
}
}
{
"status": "success",
"data": {
"bvn": "22222222222",
"firstName": "SANI",
"lastName": "IBRAHIM",
"middleName": "ALHASSAN",
"gender": "male",
"dateOfBirth": "1995-10-15",
"mobile": "08012345678",
"enrollmentBank": "011",
"image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII="
}
}
{
"status": "success",
"message": "WAEC Exam Pin(s) purchased successfully!",
"reference": "EXPIN-12-1754321234-ABCDE",
"exam_board": "WAEC",
"quantity": 2,
"unit_price": 3700,
"total_cost": 7400,
"pins": [
{
"pin": "13664234543543",
"serial_number": "WRN192476073",
"pin_content": "13664234543543<=>WRN192476073"
},
{
"pin": "66425345434331",
"serial_number": "WRN192476054",
"pin_content": "66425345434331<=>WRN192476054"
}
]
}