How to make and process an API call in 2 easy steps

Once you have your API credentials, you are now able to make an API call. This is a 2-step process as follows:

  1. Make a HTTP request to the required API endpoint with the appropriate HTTP header and body parameters.
  2. Process the HTTP response containing the status and data content returned after making the HTTP request.

API protocol

APIs can be made and processed natively or using any of the client libraries we have made available for different programming or scripting languages.

1. Making a HTTP request

To call the API, your application must make a HTTP request with parameters appropriate to the relevant API endpoint.

The HTTP request will typically consist of 3 parts:

  2. HTTP Header
  3. HTTP Body


The HTTP URL for the API endpoint is structured as follows:[function_name]

Where [function_name] is the endpoint of the particular API function you would like to call e.g. send_airtime or get_balance

HTTP Header

The HTTP header contains authentication, content type and acceptable response format parameters


The HTTP request MUST be authenticated using the API token as an Authorization header in the form of a Bearer token.

Authorization: Bearer a12f4f9a99be83f1e631e379834864e7


The HTTP request MUST also specify the format of the content it is sending to the server as a Content-Type header.

Supported formats include:

  • application/json
  • text/xml
Content-Type: application/json


The HTTP request MUST also specify the format of the content it would like to receive from the server as an Accept header.

Supported formats include:

  • application/json
  • text/xml
Accept: application/json


The HTTP body contains the required parameters for the specific API call in the specified acceptable response format

The HTTP body can then be sent depending on the content type specified in the HTTP header.

Supported formats include:

  • application/json
  • text/xml

Example HTTP request

POST /api/get_balance HTTP/1.1
Accept: application/json
Authorization: Bearer a12f4f9a99be83f1e631e379834864e7
Content-Type: application/json
Content-Length: 35

    "channel_type": "Airtime"
POST /api/get_balance HTTP/1.1
Accept: text/xml
Authorization: Bearer a12f4f9a99be83f1e631e379834864e7
Content-Type: text/xml
Content-Length: 89

<?xml version="1.0" encoding="utf-8"?>

2. Processing the HTTP response

Once the HTTP request has been made, the API endpoint will synchronously return a HTTP response.

The HTTP response will typically consist of 2 parts:

  1. Status Content
  2. Data Content

The HTTP response returned will depend on the acceptable response format specified in the Accept header of the HTTP request.

Supported formats include:

  • JSON (application/json)
  • XML (text/xml)

Status Content

The status contains feedback on whether the HTTP request was successful or failed.

Here are some typical status your API call may return after your request is processed:

API call executed and returned success status.
1000 FAIL
The API request is invalid. Endpoint may not exist or may be incorrectly spelt.
2000 FAIL
The API method used is invalid e.g using a GET instead of a POST
3000 FAIL
The API request is missing or has invalid parameters.
4000 FAIL
The API token is missing, invalid or has been revoked.
5000 FAIL
The API token does not have permission to call the specified endpoint.
6000 FAIL
The account was not found or does not exist.
7000 - 10000 FAIL
Typically errors specific to the endpoint called.

Data Content

The data contains information from the endpoint called in the HTTP request.

The data varies depending on the endpoint called and status of the HTTP request.

Example HTTP response

    "status": {
        "type": "SUCCESS",
        "code": "0000",
        "message": "Balance Found"
    "data": {
        "errors": [],
        "channel": {
            "type": "Airtime",
            "currency": "KES",
            "balance": "41226.00"
<?xml version="1.0" encoding="utf-8"?>
        <message>Balance Found</message>