Mobile Number Validation
Check whether a phone number is registered on Safaricom's network under a given ID type and number.
Endpoint
https://sandbox.safaricom.co.ke/v1/KYC-validation/validateIDOverview
Validates a phone number in real time against two parameters: ID Type (National ID, Military ID, or Passport) and ID Number. Returns a boolean: whether the registration on that number matches the identity details supplied.
How it works
- The partner sends the mobile number, ID type, and ID number.
- The API checks the number against Safaricom's records for that identity.
- It returns
trueif they match,falseif they don't. - The partner proceeds with onboarding, authentication, or fraud checks based on the result.
Onboarding
This is a commercial API. Write to apisupport@safaricom.co.ke or your account manager to be onboarded; a commercial agreement is required before production access.
| API calls per month | Charge (KES, excl. VAT) |
|---|---|
| 0 to 200,000 | 4.50 |
| 200,001 to 500,000 | 4.28 |
| 500,001 to 1,000,000 | 3.94 |
| 1,000,001 to 5,000,000 | 3.60 |
| 5,000,000 and above | 3.15 |
Charges don't apply to unsuccessful API calls.
Prerequisites
- Daraja account and sandbox app.
- Signed commercial agreement.
- Live Pay Bill/Till with Business Admin/Manager operators created, for Go Live.
Request
{
"requestRefID": "{{$timestamp}}",
"shortCode": "12345",
"msisdn": "254710860780",
"idType": "01",
"idNumber": "454353453"
}| Field | Description | Sample value |
|---|---|---|
requestRefID | Unique string per request, generated by your system. | 83a2-4b44-aaffcb3f93 |
shortCode | Your Pay Bill/Till number. | 776700 |
msisdn | Number to validate, 254XXXXXXXXX. | 254722000000 |
idType | 01 National ID, 02 Military ID, 05 Passport. | 01 |
idNumber | The customer's ID number. | 45435345 |
Response
This API is synchronous: the match result comes back directly in the response, not via a callback.
Match:
{
"responseRefID": "1771929697",
"responseCode": "4000",
"responseMessage": "Details match successfully",
"status": "true"
}Mismatch:
{
"responseRefID": "1771929733",
"responseCode": "4001",
"responseMessage": "Details do not match",
"status": "false"
}Error codes
{
"responseId": "83a2-aa8bfffcb3f939",
"errorCode": "403.001",
"errorMessage": "subscription_not_available"
}{
"requestId": "a078-4d57-9460-b5782b2dcde913",
"errorCode": "400",
"errorMessage": "Bad Request - Invalid MSISDN, the value is required and start with 2547xx and contain digits only"
}| Code | Meaning |
|---|---|
403.001 | Subscription not available |
400 | Bad request, invalid MSISDN format |
401.001 | Invalid access token |
500 | Invalid parameter input |
Testing
Defect in the source material
Safaricom's own testing instructions for this page say to "select transaction status product" when creating a test app, which is the setup for the Transaction Status API, not Mobile Number Validation. The correct product to attach here, based on this API's own onboarding section, is Mobile Number Validation.
Daraja Simulator: create a test app with the Mobile Number Validation product attached.
Postman: token from https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials, then call the endpoint above.
Go Live
Requires a signed commercial agreement and a live Pay Bill, Till, or B2C account. See Organization Portal & Go Live for creating the admin/manager operators needed to complete the Go Live tab.
FAQs
No, it's commercial, charged per the pricing table above.
User signup verification, OTP delivery, fraud detection, contact data cleanup, and marketing campaign validation, per Safaricom's documentation.
No. Safaricom documents the response as strictly a true/false match result.
No, only Safaricom numbers.