Lookup Phone Number

Retrieve carrier and subscriber information for a Nigerian phone number. Returns network, line type, and identity details when available.

There are two payload responses for this endpoint based on the details returned:

• Basic
• Advanced

Phone Number Basic

[GET]

{{baseUrl}}api/v1/kyc/phone_number/basic

Header

Header	Type	Description
AppId	string	Create an app to get your app ID on dashboard here
Authorization	string	Private/secret key. Use <key> not Bearer <key>

Query parameters

Parameter	Type	Description	Required
phone_number *	string	A valid phone number	required

Sample response

Response

{
    "entity": {
        "first_name": "JOHN",
        "middle_name": "DOE",
        "last_name": "CHHUKWU",
        "gender": "Male",
        "nationality": "NGA",
        "date_of_birth": "1990-05-16",
        "msisdn": "23481222222222"
    }
}

Response Fields

Field	Type	Description
entity	object	Contains the phone number lookup response data
entity.first_name	string	First name of the phone number subscriber
entity.middle_name	string	Middle name of the phone number subscriber
entity.last_name	string	Last name of the phone number subscriber
entity.gender	string	Gender of the subscriber
entity.nationality	string	Nationality code of the subscriber (e.g., NGA)
entity.date_of_birth	string	Date of birth of the subscriber
entity.msisdn	string	Full MSISDN (international format) of the phone number

Phone Number Advance

[GET]

{{baseUrl}}api/v1/kyc/phone_number?phone_number=081123456976

Query parameters

Parameter	Type	Description	Required
phone_number *	string	A valid phone numbe	required

Sample response

Response

{
    "entity": {
        "first_name": "JOHN",
        "last_name": "DOE",
        "middle_name": "CHHUKWU",
        "date_of_birth": "1960-12-12",
        "phone_number": "08012345678",
        "photo": "BASE 64 IMAGE",
        "gender": "M",
        "customer": "9b2ac137-5360-4050-b412-4fa6728a31fb"
    }
}

Response Fields

Field	Type	Description
entity	object	Contains the advanced phone number lookup response data
entity.first_name	string	First name of the phone number subscriber
entity.last_name	string	Last name of the phone number subscriber
entity.middle_name	string	Middle name of the phone number subscriber
entity.date_of_birth	string	Date of birth of the subscriber
entity.phone_number	string	Phone number that was looked up
entity.photo	string	Base64-encoded photo of the subscriber
entity.gender	string	Gender of the subscriber
entity.customer	string	Unique customer identifier (UUID)

Test Credentials for Sandbox

phone_number = 09011111111