SMS API

This SMS API allows you to send and receive SMS messages to and from specific networks through a REST API. Each message has a unique id so that you can check the status of the SMS submitted using the given endpoint.

An API Key is used for authorization. It is obtained from the portal by administrators.

Request and Response data is formatted as JSON.

API Endpoint

Base URL endpoint can be obtained from the portal.

Example containing apikey header.

curl -X GET {{base_url}}/v1/balance \
  -H  'ApiKey: apikey_value_here'

Send Sms

Request Body Parameters

Parameter	Type	Required	Description
message	string	Yes	Message to send to the user
mobile_number	string	Yes	Mobile number for the user
product_code	string	Yes	Unique identifier code for the sms product in use.
reference	string	No	External ID to track the message
callback_url	string	No	Endpoint where to send the sms status
link_id	string	No	value of link_id received from incoming sms notification. Required for Mobile originated sms only.

Response Body Parameters

Parameter	Type	Required	Description
message_id	string	Yes	unique message id
message_count	integer	Yes	Number of message parts
message_length	integer	Yes	Number of characters for this message
message_cost	decimal	No	How many credits are to be consumed for this message . Provided only for bulk sms messages
reference	string	No	Reference value for this message as provided in the request body

Example Send SMS request:

curl -X POST {{base_url}}/v1/messages \
-H "ApiKey: api_key_value_here" \
-H "Content-Type: application/json" \
-d '{"message":"Test Message","mobile_number":"+2547XXXXXXX","product_code":"product_code_value"}'

Example Send SMS response:

  {
    "message_id": "445856428396288",
    "message_count": 1,
    "message_length": 45,
    "message_cost": 3
  }

Get Sms Status

To get sms status, use the message id to construct a GET request of the format {{base_url}}/v1/messages/{{message_id}}/status
replacing the placeholder {{message_id}} with the actual message id. Example {{base_url}}/v1/messages/445856428396288/status

Example Get Sms Status request:

curl -X GET {{base_url}}/v1/messages/445856428396288/status \
  -H "ApiKey: edededxffcfexeEwdedeRtttgtgEEEd"

Example Get Sms Status response:

  {
      "created_ts": 1741811235,
      "message_id": "445856428396288",
      "external_ref": "",
      "callback_url": "",
      "status": "delivered",
      "error_code": "",
      "error_message":"",
      "status_ts": 1741811239
  }

Possible message status values are as described below.

Status	Description
pending	Message is waiting to be processed.
sent	Message submitted to the network gateway for delivery to recipient.
failed	Message failed. Possible reasons for failure can be insufficient balance, internal error, network error, duplicated message, expired message, invalid mobile number, user in stoplist
delivered	Message delivered to the recipient
undelivered	Message undelivered to the recipient.

An error code and error_message is included when the message status is failed or undelivered. Possible reasons for status undelivered or failed:

Error Code	Description
user_optedout	User blacklisted the sender name.
carrier_violation	Message violations carrier issued guidelines.
duplicate	A similar message exists for the recipient.
expired	Message validity lapsed and hence message could not be sent.
insufficient_balance	Credits balance not enough for the message.
user_blocklisted	User is placed in the local stoplist.
network_error	The telco's network service returned an error when trying to submit a message.
internal_error	A service error occured and hence message failed to be processed.

Get Account Balance

Example Get account balance request:

curl -X GET {{base_url}}/v1/balance \
  -H "ApiKey: edededxffcfexeEwdedeRtttgtgEEEd"
  -H "Content-Type: application/json"

Example Get account balance response:

  {
    "balance": 45,
    "currency": "KShs"
  }

Response Body Parameters

Parameter	Type	Required	Description
balance	decimal	Yes	Number of credits remaining
currency	string	Yes	Currency for the balance

Sms Events Notifications

Example sms status notification:

{
  "notification_type":"sms_status",
  "version":"1",
  "data":{
    "created_ts":1741918791,
    "message_id":"445931210675200",
    "external_ref":"",
    "status":"delivered",
    "error_code":"",
    "error_message":"",
    "status_ts":1741918795
    }
}