Phone Number NIN Lookup Integration Guide
Last updated August 3rd, 2026
Overview
Phone Number NIN Lookup allows you to retrieve the NIN and NIN-linked identity details of a user using only their Nigerian phone number. The flow follows a consent-based approach: an OTP is sent to the phone number, which is then verified before the details are retrieved.
⚠️ Billing Notice: Phone Number NIN Lookup
All Phone Number NIN Lookup API requests are billable, including failed lookups (e.g. phone number not linked to a NIN). Only certain failures are non-billable:
- Internal server failures
- Provider downtime failures
- Authentication failures that occur before the provider is called
To avoid unnecessary charges:
- Validate phone numbers before calling the API (see Phone Number Formats).
- Avoid bulk or blind verification of unverified phone numbers.
- Implement throttling and monitor failed request rates.
If you need Phone Number NIN Lookup temporarily disabled to prevent charges, contact your account manager or email support@mono.co
Prerequisites
To get started, you need to:
- Sign up on the Partner Dashboard and complete KYB.
- Create a
lookupapp and retrieve your Secret key. - Retrieve your Sandbox test credentials from the Sandbox page.
Use Cases
Phone Number NIN Lookup is designed for partners who want to:
- Verify users via phone number where NIN is not readily available.
- Retrieve NIN-linked identity information for onboarding and compliance.
- Resolve NIN from phone number for downstream verification flows.
Phone Number Formats
The phone_number field must be a valid Nigerian phone number. Acceptable formats:
- 11 digits (e.g.,
07012300000) - International with plus (e.g.,
+2347012300000) - International without plus (e.g.,
2347012300000)
The number must not be less than 11 digits and cannot be more than 14 digits, plus an optional +.
Integration Steps
The flow follows a consent-based approach: consent is obtained inline by sending an OTP to the phone number. Complete the following steps:
Step 1: Initiate the Lookup
Send a POST request to the following endpoint to send an OTP to the phone number:
Request
POST https://api.withmono.com/v3/lookup/phone/initiate
Request Body Parameters
phone_number(required): The Nigerian phone number linked to the user's NIN. See Phone Number Formats for acceptable formats.
Request Headers
Include the following header in your request for authentication:
mono-sec-key(required): Your Mono secret key.
cURL Sample Request
Request
curl -X POST \
-H "Content-Type: application/json" \
-H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
-d '{
"phone_number": "07012300000"
}' \
https://api.withmono.com/v3/lookup/phone/initiate
Success Response
If the initiation request is successful, the API will respond with a reference and the OTP expiry window:
Request
{
"status": "successful",
"message": "OTP sent",
"timestamp": "2026-07-23T12:43:35.103Z",
"data": {
"reference": "421c9d0b-ec5e-4b03-9895-187531b5673d",
"expiresInSeconds": 300
}
}
The OTP expires after the number of seconds specified in expiresinseconds. Prompt the user for the OTP and submit it in the next step before expiry.
Step 2: Verify the OTP
Send a POST request to the following endpoint to verify the OTP sent to the user:
Request
POST https://api.withmono.com/v3/lookup/phone/verify
Request Body Parameters
reference(required): The reference returned from the initiate step.otp(required): The OTP received by the user.
Request Headers
Include the following header in your request for authentication:
mono-sec-key(required): Your Mono secret key.
cURL Sample Request
Request
curl -X POST \
-H "Content-Type: application/json" \
-H "mono-sec-key: YOUR_MONO_SECRET_KEY" \
-d '{
"reference": "421c9d0b-ec5e-4b03-9895-787231b1173a",
"otp": "449127"
}' \
https://api.withmono.com/v3/lookup/phone/verify
Step 3: Process the Response
Upon successful OTP verification, you will receive the NIN linked to the phone number along with the NIN-linked identity details:
Request
{
"status": "successful",
"message": "Lookup Successful",
"timestamp": "2026-07-31T11:55:37.629Z",
"data": {
"nin": "35012345678",
"first_name": "JOHN",
"last_name": "DOE",
"middle_name": "AUSTIN",
"date_of_birth": "01-12-1980",
"gender": "m",
"phone_number": "2348123456789",
"residence_address_line1": "NO 256, ANON ROAD, GARKI, ABUJA",
"photo": "base64_image_data",
"signature": "base64_signature_data"
}
}
Billing
All actual lookup attempts are billable, including requests returning 4xx client errors.
Pricing
| API call | Pricing |
| Phone number - NIN Lookup - Initiate | NGN 10 |
| Phone number - NIN Lookup - Verify | NGN 120 |
Billable events
- All actual lookup attempts, including requests returning 4xx client errors.
Non-billable events
- Internal server failures
- Provider downtime failures
- Authentication failures that occur before provider calls