Send a text message to the mobile of the recipient by SMS from a registered or branded sender.

Once completed, an Instant Callback Notification or webhook status event is sent to the endpoint URLs set to listen for delivery reports.

Endpoint


POST https://app.topups.co.ke/api/send_sms LIVE

Request


Parameter Example
Headers
Accept application/json
String | Optional
The format of the response body. Options are:
  • application/json
  • text/xml
Defaults to application/json if not specified.
Authorization Bearer a12f4f9a99be83f1e631e379834864e7
String | Required
The API token used for authorizing the API call as Bearer token.
Content-Type application/json
String | Optional
The format of the request body. Options are:
  • application/json
  • text/xml
Defaults to application/json if not specified.
Body
country KE
String | Optional
Country code of the recipient. In 2 letter international ISO format. Options are:
  • KE (Kenya)
Automatically detected if not specified.
network Safaricom
String | Optional
Mobile network of the recipient. Options are:
  • Safaricom
  • Airtel
  • Telkom
Automatically detected if not specified.
sender DEMO
String | Required
Registered branded alpha-numeric sender id of the business.
recipient 254722000000
Integer | Required
Mobile number of the recipient to messaging transaction. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX
name Jane Wanjiku
String | Optional
Name of the recipient. Useful for auto updating your contacts list.
email jane.wanjiku@example.com
String | Optional
Email address of the recipient. Useful for auto updating your contacts list.
message Jane, your payment of KES 500 has been received.
String | Required
Text message sent to the recipient.
note SMS0000001
String | Optional
A reference number or code to help identify the messaging transaction. Ideally should be unique.

Code Scripts


POST /api/send_sms HTTP/1.1
Host: app.topups.co.ke
Accept: application/json
Authorization: Bearer a12f4f9a99be83f1e631e379834864e7
Content-Type: application/json
Content-Length: 205

{
    "country": "KE",
    "network": "Safaricom",
    "sender": "DEMO",
    "recipient": "254722000000",
    "name": "Jane Wanjiku",
    "email": "jane.wanjiku@example.com",
    "message": "Jane, your payment of KES 500 has been received.",
    "note": "SMS0000001"
}
curl --request POST 'https://app.topups.co.ke/api/send_sms' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer a12f4f9a99be83f1e631e379834864e7' \
--header 'Content-Type: application/json' \
--data-raw '{
    "country": "KE",
    "network": "Safaricom",
    "sender": "DEMO",
    "recipient": "254722000000",
    "name": "Jane Wanjiku",
    "email": "jane.wanjiku@example.com",
    "message": "Jane, your payment of KES 500 has been received.",
    "note": "SMS0000001"
}'
<?php

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://app.topups.co.ke/api/send_sms',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
        "country": "KE",
        "network": "Safaricom",
        "sender": "DEMO",
        "recipient": "254722000000",
        "name": "Jane Wanjiku",
        "email": "jane.wanjiku@example.com",
        "message": "Jane, your payment of KES 500 has been received.",
        "note": "SMS0000001"
    }',
    CURLOPT_HTTPHEADER => array(
        'Accept: application/json',
        'Authorization: Bearer a12f4f9a99be83f1e631e379834864e7',
        'Content-Type: application/json'
    ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;
#!/usr/bin/python
import http.client
import json

conn = http.client.HTTPSConnection("app.topups.co.ke")
payload = json.dumps({
    "country": "KE",
    "network": "Safaricom",
    "sender": "DEMO",
    "recipient": "254722000000",
    "name": "Jane Wanjiku",
    "email": "jane.wanjiku@example.com",
    "message": "Jane, your payment of KES 500 has been received.",
    "note": "SMS0000001"
})
headers = {
    'Accept': 'application/json',
    'Authorization': 'Bearer a12f4f9a99be83f1e631e379834864e7',
    'Content-Type': 'application/json'
}
conn.request("POST", "/api/send_sms", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require "uri"
require "json"
require "net/http"

url = URI("https://app.topups.co.ke/api/send_sms")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Accept"] = "application/json"
request["Authorization"] = "Bearer a12f4f9a99be83f1e631e379834864e7"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
    "country": "KE",
    "network": "Safaricom",
    "sender": "DEMO",
    "recipient": "254722000000",
    "name": "Jane Wanjiku",
    "email": "jane.wanjiku@example.com",
    "message": "Jane, your payment of KES 500 has been received.",
    "note": "SMS0000001"
})

response = https.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient().newBuilder()
    .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"country\": \"KE\",\r\n    \"network\": \"Safaricom\",\r\n    \"name\": \"Jane Wanjiku\",\r\n    \"mobile\": \"254722000000\",\r\n    \"email\": \"jane.wanjiku@example.com\",\r\n    \"currency\": \"KES\",\r\n    \"amount\": \"100\",\r\n    \"note\": \"SMS0000001\"\r\n}");
Request request = new Request.Builder()
    .url("https://app.topups.co.ke/api/send_sms")
    .method("POST", body)
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer a12f4f9a99be83f1e631e379834864e7")
    .addHeader("Content-Type", "application/json")
    .build();
Response response = client.newCall(request).execute();
var client = new RestClient("https://app.topups.co.ke/api/send_sms");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Accept", "application/json");
request.AddHeader("Authorization", "Bearer a12f4f9a99be83f1e631e379834864e7");
request.AddHeader("Content-Type", "application/json");
var body = @"{
    " + "\n" +
    @"    ""country"": ""KE"",
    " + "\n" +
    @"    ""network"": ""Safaricom"",
    " + "\n" +
    @"    ""sender"": ""DEMO"",
    " + "\n" +
    @"    ""recipient"": ""254722000000"",
    " + "\n" +
    @"    ""name"": ""Jane Wanjiku"",
    " + "\n" +
    @"    ""email"": ""jane.wanjiku@example.com"",
    " + "\n" +
    @"    ""message"": ""Jane, your payment of KES 500 has been received."",
    " + "\n" +
    @"    ""note"": ""SMS0000001""
    " + "\n" +
    @"}";
request.AddParameter("application/json", body,  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://app.topups.co.ke/api/send_sms',
    'headers': {
        'Accept': 'application/json',
        'Authorization': 'Bearer a12f4f9a99be83f1e631e379834864e7',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "country": "KE",
        "network": "Safaricom",
        "sender": "DEMO",
        "recipient": "254722000000",
        "name": "Jane Wanjiku",
        "email": "jane.wanjiku@example.com",
        "message": "Jane, your payment of KES 500 has been received.",
        "note": "SMS0000001"
    })
};
request(options, function (error, response) {
if (error) throw new Error(error);
    console.log(response.body);
});
package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

url := "https://app.topups.co.ke/api/send_sms"
method := "POST"

payload := strings.NewReader(`{`+"
"+`
    "country": "KE",`+"
"+`
    "network": "Safaricom"`+"
"+`
    "sender": "DEMO",`+"
"+`
    "recipient": "254722000000",`+"
"+`
    "name": "Jane Wanjiku",`+"
"+`
    "email": "jane.wanjiku@example.com",`+"
"+`
    "message": "Jane, your payment of KES 500 has been received.",`+"
"+`
    "note": "SMS0000001",`+"
"+`
}`)

client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)

if err != nil {
    fmt.Println(err)
    return
}
req.Header.Add("Accept", "application/json")
req.Header.Add("Authorization", "Bearer a12f4f9a99be83f1e631e379834864e7")
req.Header.Add("Content-Type", "application/json")

res, err := client.Do(req)
if err != nil {
    fmt.Println(err)
    return
}
defer res.Body.Close()

body, err := ioutil.ReadAll(res.Body)
if err != nil {
    fmt.Println(err)
    return
}
fmt.Println(string(body))
}

Response


Parameter Example
status
type SUCCESS
String
Indication of whether the API call executed successfully or failed. Options are:
  • SUCCESS
  • FAIL
code 0000
Numeric
Identifier of the API call result status
message Messaging Requested
String
Description of the API call result status
data
error []
Array of Strings
A list of errors found when the API call fails. Returns empty if none are found.
sender
name Demo Limited
String
Name of the sender. Typically the name of the business.
mobile 254733000000
Integer
Mobile number of the sender. Typically the mobile number of the business. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX
email admin@demo.com
String
Email address of the sender. Typically the email address of the business.
recipient
name Jane Wanjiku
String
Name of the recipient.
mobile 254722000000
Integer
Mobile number of the recipient. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX
email jane.wanjiku@example.com
String
Email address of the recipient.
transaction
type Messaging
String
Type of the transaction. Options are:
  • Messaging
reference G3DEFJKRWU
String
Unique code identifying the messaging transaction. Useful when correlating webhook events.
date 2022-09-24 09:45:35
String
Date when the messaging transaction was requested.
status Requested
String
Status of the messaging transaction. Options are:
  • Requested
  • Cancelled
currency KES
String
Currency code of the messaging transaction. In 3 letter international ISO format. Options are:
  • KES (Kenya Shilling)
amount 100
Integer
Amount of airtime sent to the recipient.
note SMS0000001
String
A reference number or code to help identify the messaging transaction. Ideally should be unique.
code R220925.0018.220016
String
Unique identifier from the mobile messaging provider. Usually blank unless the transaction was cancelled.
source API
String
Origin of the transaction request. Options are:
  • API
country KE
String
Country code of the recipient. In 2 letter international ISO format. Options are:
  • KE (Kenya)
network Safaricom
String
Mobile network of the recipient. Options are:
  • Safaricom
  • Airtel
  • Telkom
messaging
sender DEMO
String
Registered branded alpha-numeric sender id of the business.
recipient 254722000000
Integer
Mobile number of the recipient. Expected format to have country code without the plus (+) e.g 2547XXXXXXXX.
message Jane, your payment of KES 500 has been received.
String
Text message sent to the recipient.
channel
type Messaging
String
Type of channel. Options are:
  • Messaging
currency KES
String
Currency of your balance
balance 2567.00
Numeric
Balance of the specified channel

Success Example


{
    "status": {
        "type": "SUCCESS",
        "code": "0000",
        "message": "Messaging Requested"
    },
    "data": {
        "errors": [],
        "sender": {
            "name": "Demo Limited",
            "mobile": "254733000000",
            "email": "admin@demo.com"
        },
        "recipient": {
            "name": "Jane Wanjiku",
            "mobile": "254722000000",
            "email": "jane.wanjiku@example.com"
        },
        "transaction": {
            "type": "Messaging",
            "reference": "G3DEFJKRWU",
            "date": "2022-09-24 09:45:35",
            "status": "Requested",
            "currency": "KES",
            "amount": "0.35",
            "note": "SMS0000001",
            "code": "",
            "source": "API",
            "country": "KE",
            "network": "Safaricom"
        },
        "messaging": {
            "sender": "DEMO",
            "recipient": "254722000000",
            "message": "Jane, your payment of KES 500 has been received."
        },
        "channel": {
            "type": "Messaging",
            "currency": "KES",
            "balance": "2567.00"
        }
    }
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
    <status>
        <type>SUCCESS</type>
        <code>0000</code>
        <message>Messaging Requested</message>
    </status>
    <data>
        <errors/>
        <sender>
            <name>Demo Limited</name>
            <mobile>254733000000</mobile>
            <email>admin@demo.com</email>
        </sender>
        <recipient>
            <name>Jane Wanjiku</name>
            <mobile>254722000000</mobile>
            <email>jane.wanjiku@example.com</email>
        </recipient>
        <transaction>
            <type>Messaging</type>
            <reference>G3DEFJKRWU</reference>
            <date>2022-09-24 09:45:35</date>
            <status>Requested</status>
            <currency>KES</currency>
            <amount>0.35</amount>
            <note>SMS0000001</note>
            <code/>
            <source>API</source>
            <country>KE</country>
            <network>Safaricom</network>
        </transaction>
        <messaging>
            <sender>DEMO</sender>
            <recipient>254722000000</recipient>
            <messaging>Jane, your payment of KES 500 has been received.</messaging>
        </messaging>
        <channel>
            <type>Messaging</type>
            <currency>KES</currency>
            <balance>2567.00</balance>
        </channel>
    </data>
</xml>

Status


Code
0000 SUCCESS
Balance Found
1000 FAIL
Invalid API Request
2000 FAIL
Invalid Request Method
3000 FAIL
Missing or Invalid Parameters
4000 FAIL
Invalid API Token
5000 FAIL
Request Not Allowed
6000 FAIL
Invalid Account
7000 FAIL
Insufficient Balance
8000 FAIL
Messaging Cancelled
9000 FAIL
Gateway Error

Fail Example


{
    "status": {
        "type": "FAIL",
        "code": "3000",
        "message": "Missing or Invalid Parameters"
    },
    "data": {
        "errors": [
            "'mobile is invalid'",
            "'amount is required.'"
        ]
    }
}
<?xml version="1.0" encoding="utf-8"?>
<xml>
    <status>
        <type>FAIL</type>
        <code>3000</code>
        <message>Missing or Invalid Parameters</message>
    </status>
    <data>
        <errors>
            <error>'mobile is invalid'</error>
            <error>'amount is required.'</error>
        </errors>
    </data>
</xml>