Phone Number Verification API

Verify phone numbers and retrieve associated user information for Uganda mobile numbers using Marz Pay

Overview

The Phone Number Verification API allows you to verify Uganda mobile numbers and retrieve associated user information including names and other details. This service is particularly useful for KYC (Know Your Customer) processes and user verification.

How Phone Verification Works

  1. You send a verification request with the phone number
  2. System queries the mobile network database
  3. Returns user information if the number is registered
  4. Provides verification status and user details

API Base URL

All phone verification API requests should be made to the following base URL:

https://wallet.wearemarz.com/api/v1

Authentication

All API requests require authentication using your API key. Include the API key in the Authorization header with Basic Auth format.

Authorization: Basic YOUR_API_CREDENTIALS

Format: YOUR_API_CREDENTIALS = base64_encode("your_api_key:your_api_secret")

Verify Phone Number

Verify a phone number and retrieve associated user information.

Endpoint

POST /api/phone-verification/verify

Request Headers

Content-Type: application/json
Authorization: Basic YOUR_API_CREDENTIALS

Request Body

{
  "phone_number": "2567XXXXXXXX"
}

Parameters

  • phone_number (required): Uganda phone number in format 256XXXXXXXXX

Success Response

{
  "success": true,
  "message": "Phone number verified successfully",
  "data": {
    "phone_number": "2567XXXXXXXX",
    "first_name": "MARY",
    "last_name": "NAKAMYA",
    "full_name": "MARY NAKAMYA",
    "verification_status": "verified"
  },
  "phone_number": "2567XXXXXXXX",
  "verified_at": "2024-01-15T10:30:00.000000Z"
}

Response Fields

  • success: Boolean indicating if verification was successful
  • message: Human-readable success message
  • data.phone_number: The verified phone number
  • data.first_name: User's first name (if available)
  • data.last_name: User's last name (if available)
  • data.full_name: Combined first and last name
  • data.verification_status: Always "verified" for successful responses
  • phone_number: The phone number that was verified
  • verified_at: ISO timestamp of verification

Error Response

{
  "success": false,
  "message": "Phone number not found or not registered",
  "error": "Number not found in database"
}

Service Information

Get information about the phone verification service and its status.

Endpoint

GET /api/phone-verification/service-info

Response

{
  "success": true,
  "data": {
    "service_name": "Phone Number Verification",
    "provider": "Phone Number Verification",
    "type": "verification",
    "country": "UG",
    "currency": "UGX",
    "is_active": true,
    "api_configured": true
  }
}

Response Fields

  • service_name: Name of the verification service
  • provider: Service provider name
  • type: Service type (verification)
  • country: Supported country code
  • currency: Supported currency
  • is_active: Whether the service is currently active
  • api_configured: Whether API credentials are properly configured

Subscription Status

Check if your business has an active subscription to the phone verification service.

Endpoint

GET /api/phone-verification/subscription-status

Response

{
  "success": true,
  "data": {
    "is_subscribed": true,
    "service_name": "Phone Number Verification"
  }
}

Code Examples

cURL

curl -X POST "https://wallet.wearemarz.com/api/phone-verification/verify" \
						  -H "Content-Type: application/json" \
						  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
						  -d '{
						    "phone_number": "2567XXXXXXXX"
						  }'

JavaScript (Fetch)

const response = await fetch('https://wallet.wearemarz.com/api/phone-verification/verify', {
						  method: 'POST',
						  headers: {
						    'Content-Type': 'application/json',
						    'Authorization': 'Basic YOUR_API_CREDENTIALS'
						  },
						  body: JSON.stringify({
						    phone_number: '2567XXXXXXXX'
						  })
						});

const data = await response.json();

if (data.success) {
  console.log('User:', data.data.full_name);
  console.log('Phone:', data.data.phone_number);
  console.log('Status:', data.data.verification_status);
} else {
  console.error('Verification failed:', data.message);
}

PHP (Guzzle)

$client = new \GuzzleHttp\Client();

$response = $client->post('https://wallet.wearemarz.com/api/phone-verification/verify', [
						    'headers' => [
						        'Content-Type' => 'application/json',
						        'Authorization' => 'Basic YOUR_API_CREDENTIALS'
						    ],
						    'json' => [
						        'phone_number' => '2567XXXXXXXX'
						    ]
						]);

$data = json_decode($response->getBody(), true);

if ($data['success']) {
    echo "User: " . $data['data']['full_name'] . "\n";
    echo "Phone: " . $data['data']['phone_number'] . "\n";
    echo "Status: " . $data['data']['verification_status'] . "\n";
} else {
    echo "Verification failed: " . $data['message'] . "\n";
}

Error Codes

Code Description
400 Bad Request - Invalid phone number format
401 Unauthorized - Invalid API key
403 Forbidden - Service not subscribed
404 Not Found - Phone number not found
500 Internal Server Error

Best Practices

  • Always use the correct phone number format (256XXXXXXXXX)
  • Handle errors gracefully and provide user-friendly messages
  • Cache verification results to avoid repeated API calls
  • Respect rate limits and implement proper retry logic
  • Store API keys securely and never expose them in client-side code