Skip to main content
POST
Validate phone number
Validates a mobile money account by checking the phone number format and country support, and (where the corridor supports it) resolving the real account holder name via a live provider lookup — reducing the risk of sending funds to the wrong recipient. Also handles paybill and till numbers: set accountType to paybill or till and pass shortCode instead of phoneNumber.
phoneNumber is required unless accountType is paybill or till, in which case shortCode is required instead. This can’t be expressed as a flat “required” list — see the field descriptions below.
Pass accountName to get back a nameMatch score against the account’s real, resolved name — useful for confirming you have the right recipient before a payout.
This replaces the older standalone /name-lookup endpoint, which is deprecated.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

phoneNumber is required unless accountType is 'paybill' or 'till'; shortCode is required when accountType is 'paybill' or 'till'.

accountType
enum<string>
default:mobile_money

What to validate. Defaults to mobile_money; paybill and till take shortCode instead of phoneNumber.

Available options:
mobile_money,
paybill,
till
phoneNumber
string

Required unless accountType is paybill or till. Send in international format, including the country code.

Example:

"+254712345678"

shortCode
string

Required when accountType is paybill or till. The M-PESA shortcode.

Example:

"247247"

accountReference
string

Account number on a paybill — what a payer would enter. Paybill only.

Example:

"0670179741746"

countryCode
string

Country code (ISO-2). Only needed for paybill and till, where it defaults to KE.

Example:

"KE"

network
enum<string>

Mobile network, used to route the name lookup. Optional — resolved from the phone number prefix when omitted.

Available options:
MTN,
AIRTEL,
VODAFONE,
TIGO,
YAS,
ORANGE,
NOT_SUPPORTED,
ZAMTEL,
MPESA,
CHECKOUT,
BKTRX,
CRDTRX,
MOOV,
TMONEY,
FREE,
EXPRESSO,
HALOPESA,
VODACOM,
WAVE
Example:

"MPESA"

accountName
string

Name you expect on this account. Returns a nameMatch score against the real one.

Example:

"Jane Doe"

Response

success
boolean
Example:

true

message
string
Example:

"Phone number validated successfully."

data
object