Statum Company Logo

Getting started

This guide describes how to create an account, get credentials to start building your project and connect to our interface for testing your project.

Getting access to Statum Developer is as simple as registering your name, email address, organization and creating a password. After you authenticate your email address (which is delivered to your email inbox), you are ready to start developing your first project.

Once you log in to Statum Developer, you will see the dashboard. This dashboard is your login home page where you can create and manage your projects.

Below is the key information to get you started.... and, we can't wait to see what you build.

API integration flow

All our API request and response parameters - including errors - are encoded in JSON. API response status codes and error codes comply with HTTP status codes as defined in RFC 2616.

This documentation provides sample codes and JSON responses next to these APIs.

The diagram below shows how a request is relayed from your application to the service provider through our gateway and how we forward the API result to your callback URL.

Statum API flow

API request headers

These are the standard request headers that are needed when authenticating with the API.

Parameter Type Description Example
Authorization String This is the base64 encoded consumerKey:consumerSecret in an HTTP Authorization: Basic header Basic dG9wc2VjcmV0OjEyMzQ=
Content-Type String The requests content type application/json
Accept String The requests response type. (Optional) application/json

Sample request headers

  'Authorization: Basic dG9wc2VjcmV0OjEyMzQ=',
  'Content-Type: application/json',
  'Accept: application/json',

API requests

In addition to the API standard request headers , the body of the request should contain the specific required fields. The requests should be encoded in JSON format.

All API requests should be sent to https://api.statum.co.ke/api/v2/{command}, where command is the API call you wish to execute, with the parameters included either in the POST or the URL (GET).

Sample Send SMS API request

{
  "sender_id": "Statum",
  "phone_number": "254712345678",
  "message": "This is a test Message through our API"
}

API responses

On every API invocation, an API response is returned in JSON format. This API response JSON object response contains status_code, description and request_id.

The status_code field, can be either "200", "400s" or "500s". This status_code field can be used to determine whether your API call request was successful or not.

If the status_code is anything other than a 200 OK, an API error status_code and description will also be returned.

The request_id field uniquely identifies the request within the gateway. The same request_id is used in the API result callback to identify the specific request.

If you need to contact us about a specific request, providing the request identifier will ensure the fastest possible resolution.

Sample successful API call

{
  "status_code": 200,
  "description": "Operation successful",
  "request_id": "9V7NcW1QMvWkQcceMnn3MKfmczdBeE1a"
}

API results or notifications

An API result or notification is information sent to your application whenever we need to let you know that something has occurred. For example, when a message is delivered to the recipient or a payment has been made successfully, we immediately let you know via a notification with the details of that transaction.

Notifications are sent to the callback URL you set on your application for a given product. You can set your application’s callback URLs from the dashboard.

API result JSON objects will contain a 200 result_code for successful transactions. A success result_desc will also be sent to your web hook. Any other result_code other than 200 OK means the transaction has failed for a reason contained on the result description.
The request_id returned on the API invocation is also returned to identify the specific request on the API result notification.

Sample SMS API result notification

{
  "result_code": "200",
  "result_desc": "Success",
  "request_id": "9V7NcW1QMvWkQcceMnn3MKfmczdBeE1a"
}
Copyright © 2021 Statum Ltd