API Documentation - MarzKYC

Getting Started

Welcome to the MarzKYC API! This documentation will help you integrate KYC (Know Your Customer) verification services into your application. Our API provides secure, reliable verification for phone numbers, bank accounts, and NIN (National Identification Numbers).

What is KYC Verification?

KYC (Know Your Customer) verification helps you validate customer information to prevent fraud, comply with regulations, and build trust. Our API provides:

Phone Number Verification: Verify phone numbers to ensure they're active and valid
Bank Account Verification: Validate bank account numbers and account holder names
NIN Verification: Verify National Identification Numbers (coming soon)

Base URL

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

All API endpoints are prefixed with this base URL. Make sure to use HTTPS in production.

API Credentials

To get started, you'll need API credentials. Sign up for an account, subscribe to the verification services you need, and generate your API keys.

Sign Up Now →

Quick Start Workflow

Sign up and create your account
Subscribe to the verification services you need (Phone, Bank Account, etc.)
Generate your API credentials in the API Keys section
Make your first verification request using the examples below
Check your account balance before making requests
Monitor your API usage in the API Request History

Authentication

Step-by-Step: Getting Your API Credentials

1. Sign up or log in to your MarzKYC account at https://kyc.wearemarz.com/
2. Navigate to Dashboard → Settings & Tools → API Keys
3. Click "Create New API Key" and give it a descriptive name (e.g., "Production API" or "Test Environment")
4. Important: Copy your API Key and API Secret immediately. The secret is only shown once and cannot be retrieved later.
5. Store your credentials securely. Never commit them to version control or expose them publicly.

How HTTP Basic Authentication Works

All API requests require authentication using HTTP Basic Authentication. This ensures secure access to verification services:

API Key = Username (used as the first part of credentials)
API Secret = Password (used as the second part of credentials)
Format: API_KEY:API_SECRET
This combination is base64-encoded and sent in the Authorization header

Security Note: Always use HTTPS in production. Never expose your API credentials in client-side code. Store credentials securely in environment variables or secure configuration files.

Service Subscription Required

Before making verification requests, you must subscribe to the specific verification service you want to use:

Navigate to Services → Marketplace in your dashboard
Browse available verification services
Subscribe to the services you need (Phone Verification, Bank Account Verification, etc.)
Ensure your account has sufficient balance for verification requests

Tip: Each verification request is charged per successful verification. Failed requests are not charged.

cURL Example

Using the -u flag automatically handles Basic Auth:

                                    curl -X POST "https://kyc.wearemarz.com/api/v1/verify/phone" \
  -u "YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "256700000000"
  }'
                                

Replace YOUR_API_KEY and YOUR_API_SECRET with your actual credentials.

PHP Example

Using CURLOPT_USERPWD for Basic Auth:

                                    // Your API credentials
$apiKey = 'sk_your_actual_api_key_here';
$apiSecret = 'your_actual_api_secret_here';

// Initialize cURL
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://kyc.wearemarz.com/api/v1/verify/phone',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => $apiKey . ':' . $apiSecret, // Basic Auth
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
    ],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode([
        'phone_number' => '256700000000',
    ]),
]);

$response = curl_exec($curl);
$statusCode = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$error = curl_error($curl);
curl_close($curl);

if ($error) {
    echo "cURL Error: " . $error;
} else {
    $result = json_decode($response, true);
    if ($result['success']) {
        echo "Success! " . $result['message'];
    } else {
        echo "Error: " . $result['message'];
    }
}
                                

JavaScript (Fetch) Example

Using base64 encoding for Basic Auth header:

                                    // Your API credentials
const apiKey = 'sk_your_actual_api_key_here';
const apiSecret = 'your_actual_api_secret_here';

// Encode credentials for Basic Auth
const credentials = btoa(apiKey + ':' + apiSecret);

fetch('https://kyc.wearemarz.com/api/v1/verify/phone', {
    method: 'POST',
    headers: {
        'Authorization': 'Basic ' + credentials,
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        phone_number: '256700000000'
    })
})
.then(response => response.json())
.then(data => {
    if (data.success) {
        console.log('Success!', data.message);
    } else {
        console.error('Error:', data.message);
    }
})
.catch(error => {
    console.error('Request failed:', error);
});
                

Python (requests) Example

                                    import requests
import json

# Your API credentials
api_key = 'sk_your_actual_api_key_here'
api_secret = 'your_actual_api_secret_here'

url = 'https://kyc.wearemarz.com/api/v1/verify/phone'

headers = {
    'Content-Type': 'application/json'
}

data = {
    'phone_number': '256700000000'
}

# Basic Auth with requests library
response = requests.post(
    url,
    headers=headers,
    auth=(api_key, api_secret),
    json=data
)

result = response.json()
if result['success']:
    print('Success!', result['message'])
else:
    print('Error:', result['message'])
                                

GET /api/v1/account/balance

Check Account Balance

Get your current account balance to ensure you have sufficient funds for verification requests. Each successful verification is charged from your account balance. This endpoint requires authentication but no additional parameters.

Important: Always check your balance before making bulk verification requests. Failed verifications are not charged, but successful ones are deducted from your balance.

Example Request

                                curl -X GET "https://kyc.wearemarz.com/api/v1/account/balance" \
  -u "YOUR_API_KEY:YOUR_API_SECRET"
                            

Success Response (200 OK)

                                {
  "success": true,
  "data": {
    "balance": 100000.00,
    "currency": "UGX"
  }
}
                            

Response Fields:

balance - Current account balance in UGX (decimal number)
currency - Always "UGX" for Uganda Shillings

Error Response (401 - Unauthorized)

                                {
  "success": false,
  "message": "Invalid API credentials.",
  "error": "invalid_credentials"
}
                            

POST /api/v1/verify/phone

Verify Phone Number

Verify a phone number to check if it's active and valid. This is useful for customer onboarding, fraud prevention, and ensuring contact information accuracy. You must be subscribed to the Phone Number Verification service.

Use Cases: Customer onboarding, identity verification, fraud prevention, contact validation, and ensuring phone numbers are active before sending important communications.

Request Body

Field	Type	Required	Description
phone_number	string	Yes	Phone number (can be in format: 256XXXXXXXXX, 0XXXXXXXXX, or XXXXXXXXX)

Example Request

                                curl -X POST "https://kyc.wearemarz.com/api/v1/verify/phone" \
  -u "YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "256700000000"
  }'
                            

Success Response (200 OK)

                                {
  "success": true,
  "message": "Phone number verified successfully",
  "data": {
    "verified": true,
    "network": "MTN",
    "status": "active"
  },
  "phone_number": "256700000000"
}
                            

POST /api/v1/verify/bank-account

Verify Bank Account

Validate bank account numbers and retrieve account holder information. This helps verify customer banking details for payments, payouts, and financial transactions. You must be subscribed to the Bank Account Verification service.

Use Cases: Payment processing, payout verification, financial onboarding, fraud prevention, and ensuring bank account details are correct before processing transactions.

📋 Important: Get Supported Banks First

Before verifying a bank account, you should first retrieve the list of supported banks using the GET /api/v1/banks endpoint. This ensures you use the correct bank name format.

                                curl -X GET "https://kyc.wearemarz.com/api/v1/banks" \
  -u "YOUR_API_KEY:YOUR_API_SECRET"
                            

See the "Get Supported Banks" section below for the response format.

Request Body

Field	Type	Required	Description
bank_name	string	Yes	Name of the bank (must match a bank from the supported banks list - use GET /api/v1/banks to get the list)
account_number	string	Yes	Bank account number

Example Request

                                curl -X POST "https://kyc.wearemarz.com/api/v1/verify/bank-account" \
  -u "YOUR_API_KEY:YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "bank_name": "Centenary Bank",
    "account_number": "1234567890"
  }'
                            

Get Supported Banks

GET /api/v1/banks

Get a list of all supported banks for verification. Use this endpoint to get the exact bank names that are accepted by the verification endpoint.

                                curl -X GET "https://kyc.wearemarz.com/api/v1/banks" \
  -u "YOUR_API_KEY:YOUR_API_SECRET"
                            

Success Response (200 OK)

                                    {
  "success": true,
  "message": "Supported banks retrieved successfully",
  "data": {
    "banks": [
      {
        "id": 1,
        "name": "Centenary Bank",
        "code": "CENTENARY"
      },
      {
        "id": 2,
        "name": "Equity Bank",
        "code": "EQUITY"
      },
      {
        "id": 3,
        "name": "Stanbic Bank",
        "code": "STANBIC"
      }
    ],
    "count": 3
  }
}
                                

Response Fields:

banks - Array of supported banks
banks[].name - Bank name to use in verification requests
banks[].code - Bank code (optional identifier)
count - Total number of supported banks

Note: Always use the exact bank name from this list when making verification requests. Bank names are case-sensitive.

Success Response (200 OK)

                                {
  "success": true,
  "message": "Bank account validated successfully",
  "data": {
    "valid": true,
    "account_name": "John Doe",
    "bank": "Centenary Bank"
  }
}
                            

GET /api/v1/requests

Get API Request History

Retrieve your complete API request history with detailed information about each verification request. Track costs, success rates, response times, and review request/response data for debugging and auditing purposes. Results are sorted by most recent first.

Benefits: Monitor your verification usage, track costs, analyze success rates, debug failed requests, and maintain audit trails for compliance purposes.

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by status: success, failed, error
service_type	string	No	Filter by service type: PhoneNumber, BankAccount, NIN
date_from	date	No	Filter from date (YYYY-MM-DD)
date_to	date	No	Filter to date (YYYY-MM-DD)
per_page	integer	No	Items per page (max: 100, default: 50)

Example Requests

Get all requests:

                                        curl -X GET "https://kyc.wearemarz.com/api/v1/requests" \
  -u "YOUR_API_KEY:YOUR_API_SECRET"
                                    

Get successful requests only:

                                        curl -X GET "https://kyc.wearemarz.com/api/v1/requests?status=success" \
  -u "YOUR_API_KEY:YOUR_API_SECRET"
                                    

Success Response (200 OK)

                                {
  "success": true,
  "data": [
    {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "endpoint": "/api/v1/verify/phone",
      "method": "POST",
      "service_type": "PhoneNumber",
      "status": "success",
      "cost": 200.00,
      "response_code": 200,
      "response_time_ms": 1250.50,
      "created_at": "2025-11-02 14:30:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 50,
    "total": 250
  }
}
                            

Pricing & Billing

MarzKYC uses a pay-per-verification model. You only pay for successful verifications, making it cost-effective for your business.

How Pricing Works

Pay Per Verification: Each service has its own pricing. Check the Marketplace for current rates.
Success-Only Billing: You're only charged for successful verifications. Failed or invalid requests are free.
Prepaid Balance: Top up your account balance and use it for verification requests. No monthly fees or subscriptions required.
Transparent Pricing: See exactly what each verification costs before making requests. Check your balance anytime.

💡 Cost Optimization Tips

Validate input data on your end before making API calls to avoid unnecessary charges
Use the Get Supported Banks endpoint to ensure correct bank names before verification
Monitor your API request history to track costs and identify patterns
Set up balance alerts to avoid service interruptions

Error Codes & Troubleshooting

Understanding error responses helps you handle edge cases and improve your integration. All errors follow a consistent format with a success: false flag and an error message.

401 - Unauthorized

Invalid or missing API credentials. This usually means:

API key or secret is incorrect
Credentials are not properly encoded in the Authorization header
API key has been deactivated

Solution: Verify your API credentials in the dashboard and ensure Basic Auth is properly implemented.

402 - Insufficient Balance

Your account balance is too low to complete the verification request.

Solution: Top up your account balance through the dashboard. Check your balance using the Account Balance endpoint before making requests.

403 - Forbidden

You don't have access to the requested service. This means:

You haven't subscribed to the verification service
The service is not available or has been disabled

Solution: Subscribe to the service in the Marketplace section of your dashboard.

422 - Validation Error

Invalid request parameters. Common causes:

Missing required fields (e.g., phone_number, bank_name, account_number)
Incorrect data format (e.g., invalid phone number format, wrong bank name)
Invalid data types or values

Solution: Check the error response for specific field errors. Use the Get Supported Banks endpoint to ensure correct bank names.

500 - Server Error

An internal server error occurred on our end.

Solution: Retry the request after a few moments. If the error persists, check our status page or contact support with the request UUID from your API history.

503 - Service Unavailable

The verification service is temporarily unavailable or not configured.

Solution: Wait a few moments and retry. If the issue persists, contact support.

Error Response Format

All error responses follow this structure:

                                {
  "success": false,
  "message": "Human-readable error message",
  "error": "error_code",
  "errors": {
    "field_name": ["Specific validation errors"]
  }
}
                            

Always check the message field for user-friendly error descriptions and the errors object for field-specific validation issues.

Need Help?

Our team is here to help you integrate MarzKYC into your application. Get in touch for technical support, custom integrations, or any questions.

Sign Up Free