Peleza — Trust built on data
🇰🇪 KYC
On this page

Phone Number

Verify a Kenyan phone number via POST /api/v1/phone-number/ke. Send phone_number only (plus consent). Accepts 07… / 01…, +254, or 254 formats (normalized to local 10 digits). Returns name, account, institution, and validity flags.

Test data

Sandbox test data

Use these values against the sandbox host. Click a value to copy it.

Sandbox test phones

Request

POST/api/v1/phone-number/ke
{{baseUrl}}/api/v1/phone-number/ke
HeaderTypeDescription
AuthorizationstringBearer YOUR_ACCESS_TOKEN from the OAuth client-credentials flow
Content-Typestringapplication/json

Body Parameters

ParameterTypeDescriptionRequired
phone_numberstringMSISDN — 10 digits starting with 07 or 01 (e.g. 0712345678). +254 / 254 prefixes are accepted and normalizedrequired
consentbooleanMust be true — confirms data-subject consent to perform this verificationrequired
customer_numberstringOptional reference for your own tracking (max 255 characters)optional

Sample request & response

Request payload for Sample request & response:

Sample dataRequest payload
{
  "phone_number": "0712845631",
  "consent": true
}

Expected response for Sample request & response:

200 OKSample dataExpected response
{
  "success": true,
  "response_code": 200,
  "message": "Phone Number Details Fetched Successfully",
  "data": {
    "name": "joe doe",
    "account": "254712845631",
    "is_active": true,
    "institution": "Safaricom",
    "phone_number": "254712845631"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response Fields

FieldTypeDescription
successbooleanWhether the request succeeded
response_codenumberApplication response code (typically mirrors HTTP)
messagestringHuman-readable status message
dataobjectPayload for the verified resource
request_idstringUUID for support and audit trails
data.namestringRegistered name on the phone account
data.accountstringAccount MSISDN (e.g. 2547…)
data.is_activebooleanWhether the phone line appears active
data.institutionstringMobile network / institution (e.g. Safaricom)
data.phone_numberstringPhone number returned (e.g. 2547…)

Error codes

Standard Peleza HTTP / response_code values (same across all API calls). Validation message text is endpoint-specific. Full reference: Error Codes.

CodeWhenBilled?
200Phone number details returned successfullyYes
400Validation — phone_number required (07…/01… after +254/254 normalization); consent must be trueNo
401Missing or invalid Bearer tokenNo
402Insufficient wallet balance or credit limitNo
403No active wallet or billing profile (or service not enabled)No
404Phone number not foundYes
408Upstream timeout / service errorNo
429Rate limitedNo
502Upstream bad or unreadable responseNo
503Verification service unavailable or request timed outNo

400 — validation

400Sample data400 — validation
{
  "success": false,
  "response_code": 400,
  "message": "Validation Error",
  "errors": {
    "phone_number": ["The phone number must be 10 digits starting with 07 or 01 (e.g., 0712845631 or 0112345678). +254 / 254 prefixes are accepted."]
  }
}

400 — consent required

400Sample data400 — consent required
{
  "success": false,
  "response_code": 400,
  "message": "Validation Error",
  "errors": {
    "consent": ["Consent must be true to perform identity verification"]
  }
}

404 — not found

404Sample data404 — not found
{
  "success": false,
  "response_code": 404,
  "message": "Phone Number Not Found",
  "errors": {
    "phone_number": ["The provided phone number does not exist in our records."]
  }
}

503 — service unavailable

503Sample data503 — service unavailable
{
  "success": false,
  "response_code": 503,
  "message": "Phone number verification service is temporarily unavailable. Please try again later.",
  "errors": {
    "phone_number": ["Verification service unavailable"]
  }
}

Set {{baseUrl}} to https://api.peleza.com (production) or https://sandbox.peleza.com (sandbox). Authenticated calls need a Bearer token from POST /api/v1/oauth/token.