- Introduction
- Get Started
- Authorization
- Get API Credentials
- How It Works
- Making API Calls
- Airtime
- Send Airtime
- Buy Airtime
- Agent Float
- Send Agent Float
- Messaging
- Send SMS
- Channels
- Get Balance
- Get Product
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.
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:
|
|
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:
|
|
Body | |
country
KE
String | Optional Country code of the recipient. In 2 letter international ISO format. Options are:
|
|
network
Safaricom
String | Optional Mobile network of the recipient. Options are:
|
|
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:
|
||
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:
|
||
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:
|
||
currency
KES
String Currency code of the messaging transaction. In 3 letter international ISO format. Options are:
|
||
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:
|
||
country
KE
String Country code of the recipient. In 2 letter international ISO format. Options are:
|
||
network
Safaricom
String Mobile network of the recipient. Options are:
|
||
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:
|
||
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>