How to Integrate a Mobile Network Lookup API in South Africa

South African mobile number prefixes do not reliably identify the current network because subscribers can port their numbers. The SIMcloud Network Lookup API checks the supplied MSISDN and returns the detected current network for the authenticated account.

This developer guide is for recharge validation, SIM inventory, onboarding and routing. For an occasional manual check, use the public SIMcloud network confirmation tool instead.

Network lookup endpoint

GET https://simcloud.co.za/api/network.php?msisdn=0821234567
Authorization: Bearer YOUR_API_TOKEN

A successful response has this shape:

{
  "status": "success",
  "msisdn": "+27821234567",
  "network": "mtn"
}

Each lookup is logged against the authenticated SIMcloud account. Use the endpoint only for authorised business purposes.

Normalise and validate the number

Accept a limited set of user formats, remove harmless spaces and punctuation, then convert the number into a consistent local representation before calling the API.

<?php

function normaliseSouthAfricanMsisdn(string $value): string
{
    $digits = preg_replace('/\D+/', '', $value) ?? '';

    if (str_starts_with($digits, '27') && strlen($digits) === 11) {
        return '0' . substr($digits, 2);
    }

    if (strlen($digits) === 10 && $digits[0] === '0') {
        return $digits;
    }

    throw new InvalidArgumentException('Invalid South African mobile number');
}

Local validation prevents avoidable requests. The API remains the authority for whether a valid-looking number matches a network.

Call the lookup API

$msisdn = normaliseSouthAfricanMsisdn('082 123 4567');
$result = simcloudRequest(
    'GET',
    '/api/network.php?msisdn=' . rawurlencode($msisdn)
);

if ($result['http_status'] === 200) {
    $network = (string) $result['body']['network'];
    $normalised = (string) $result['body']['msisdn'];
} elseif ($result['http_status'] === 404) {
    $network = null;
} elseif ($result['http_status'] === 401) {
    throw new RuntimeException('SIMcloud authentication failed');
} else {
    throw new RuntimeException(
        (string) ($result['body']['message'] ?? 'Network lookup failed')
    );
}

Use the result without overclaiming

The network result can help your application:

• Select the appropriate airtime network value.
• Filter the live data-bundle catalogue.
• Flag a mismatch between a stored network and current lookup.
• Refresh SIM inventory before a bulk recharge.
• Route an order to the correct network-specific workflow.

Choose a sensible caching policy

Do not assume a network result is permanent. Number portability means it can change. Cache only for the period justified by your workflow.

Design for many lookups

The documented endpoint handles one MSISDN per request. For a large internal list:

1. Validate and deduplicate numbers locally.
2. Create one local lookup record per unique MSISDN.
3. Use a bounded worker queue rather than parallelising without limits.
4. Store HTTP status, returned normalised number, network and lookup time.
5. Retry safe transport failures with a bounded policy.
6. Do not retry invalid 400 results unchanged.
7. Stop the queue on repeated 401 authentication failures.

Handle the API outcomes

• 200: store the normalised MSISDN, network and lookup timestamp.
• 400: mark the input invalid and request correction.
• 401: stop the integration and alert operations.
• 404: record that no network match was returned; do not invent one from the prefix.
• 405: ensure the integration is using GET.

Frequently asked questions