Timisha API Integration Page (for Developers)

Get Phone Number Details

This endpoint is used to validate a phone number and convert it to the standard 254******** format. It also indicates the local network that the phone number belongs to. NOTE: you need to have credit in your wallet to validate phone numbers at KES 0.10 per validation.

Base URL: https://api.timisha.ke/v1/msisdns/load-details

NOTE: Send a POST request

Headers

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

Json body

{
    "phone": "0782229227"
}

Sample CURL request

curl --location 'https://api.timisha.ke/v1/msisdns/load-details' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
    "phone": "0782229227"
}'

Success Response

{
    "status": true,
    "responseCode": "0200",
    "networkName": "airtel",
    "formattedPhone": "254782229227"
}

Failed Response

{
    "status": false,
    "responseCode": "0422",
    "message": "Invalid phone number"
}

Networks as shown below:

Response Parameter	Telco Company
safaricom	Safaricom PLC
airtel	Airtel Kenya Limited
telkom	Telkom Kenya Limited
equitel	Equitel (Finserve Africa Limited)

Sending SMS

a) Sending a single SMS

You can send a single SMS using POST Form data request, Json POST request and GET request

1. JSON POST Request

You can send a Json POST Request as shown below:

Base URL: https://api.timisha.ke/v1/send/message

Headers

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

Json Body

{
    "senderID": "TIMISHA",
    "message": "Dear Mercy, Your water bill of KES 8,200 is due on 02 Sept 2027. STOP *456*9*5#",
    "phone": "2547078614XX"
}

Sample CURL request

curl --location 'https://api.timisha.ke/v1/send/message' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
    "senderID": "TIMISHA",
    "message": "Dear customer, thanks for shopping with us! Bonus of 44 added to your a/c.",
    "phone": "25470786XXX"
}'

Success Response

{
   "status":true,
   "responseCode":"0200",
   "message":"Accepted",
   "messageId":"9b8a028b-f9bb-49f6-bc89-a5214ff1ba93"
}

Failed Response

{
   "status":false,
   "responseCode":"0422",
   "message":"The Sender ID is Invalid!"
}

2. POST Form Data Request

You can also send a message using a POST request with form data parameters. To do so, send the form data parameters as below:

Base URL: https://api.timisha.ke/v1/send/message

NOTE: The parameter names are case sensitive

Parameter Name	Description	Example
senderID	Your registered sender ID	TIMISHA
message	Message to be sent to the recipient	This is a sample message
phone	Recipient phone number	254722002222
api_token	Your API key	Your-api-token_HERE

Success Response

{
   "status":true,
   "responseCode":"0200",
   "message":"Accepted",
   "messageId":"9b8a028b-f9bb-49f6-bc89-a5214ff1ba93"
}

Failed Response

{
   "status":false,
   "responseCode":"0422",
   "message":"The Sender ID is Invalid!"
}

3. GET Request

You can send an SMS using a GET request. To do so send a request as below:

https://api.timisha.ke/v1/send/messageget?senderID=TIMISHA&message=Test_message&phone=0722002222&api_token=testOlBJzS6K2Obn8ynFIeuOYdDMuLrrpThApDMnI4i4Zxcapikey

Success Response

{
   "status":true,
   "responseCode":"0200",
   "message":"Accepted",
   "messageId":"9b8a01af-4233-47f5-83f8-7d12c9605e51"
}

Failed Response

{
   "status":false,
   "responseCode":"0401",
   "message":"Unauthenticated"
}

b) Bulk SMS

You can broadcast a single SMS to multiple contacts in a single request. It is recommended that you send 50 messages per request. The parameters are as below:

Base URL: https://api.timisha.ke/v1/send/bulk

Headers

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

Json Body

{
    "senderID": "TIMISHA",
    "message": "Dear member, this is a reminder that this is a test message for bulk",
    "phones": "07257125xx,2547078614xx"
}

Sample CURL request

curl --location 'https://api.timisha.ke/v1/send/bulk' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
    "senderID": "TIMISHA",
    "message": "Hello, this is a reminder that our Annual AGm is today at 2PM. Keep time.",
    "phones": "254707XXXXXX,25411XXXXX"
}'

Success Response

{
    "status": true,
    "responseCode": "0200",
    "message": "Accepted",
    "bulkId": "9b8a0969-b3ea-4ac9-a7c7-a79b53d6b019"
}

Failed Response

{
    "status": false,
    "responseCode": "0422",
    "message": "The Sender ID is Invalid!"
}

c) Personalized Messages

This is used to send multiple messages in a single request. Each phone receives a different message. It is recommended that you send 50 messages per request. The parameters are as below:

Base URL: https://api.timisha.ke/v1/send/bulk-personalized

Headers

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

Json Body

{
    "senderID": "TIMISHA",
    "messageBody": [
        {
            "phone": "2547078614xx",
            "message": "Vin, your water bill of KES 6700 is due on 23rd."
        },
         {
            "phone": "07267125xx",
            "message": "Hey Faith, your water bill of KES 400 is due today."
        }
    ]
}

Sample CURL request

curl --location 'https://api.timisha.ke/v1/send/bulk-personalized' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
    "senderID": "TIMISHA",
    "messageBody": [
        {
            "phone": "2547078614xx",
            "message": "Caro, your water bill of KES 6700 is due on 23rd."
        },
         {
            "phone": "2541118810xx",
            "message": "Dear James, your water bill of KES 40100 is due on 31st."
        }
    ]
}'

Success Response

{
   "status":true,
   "responseCode":"0200",
   "message":"Accepted",
   "bulkId":"9b8a0f37-419d-454d-931d-0f5d4ddc4xxx"
}

Failed Response

{
   "status":false,
   "responseCode":"0422",
   "message":"The Sender ID is Invalid!"
}

d) SMS Delivery Status (Callback URL)

You can register a callback URL on your account to receive delivery status of messages sent out. To do so, go to “Company Management” then View/Update Details” to update your callback URL. The following Json payload will be sent to your end point.

{
   "deliveryStatus":"DeliveredToTerminal",
   "deliveryTime":"2024-03-12 11:52:47",
   "reference":"9b8b7a66-abbc-44bd-9098-4331fb264400",
   "msisdn":"25470xxxxxx",
   "cost": "0.12"
}

e) SMS Delivery Status (Query)

You can query delivery status of a message using the message id generated when sending a message:

Base URL: https://api.timisha.ke/v1/dlr

Headers

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

Json Body

{
    "messageId": "9b899e2d-fde0-4361-997b-b802364ff736"
}

Sample CURL request

curl --location 'https://api.timisha.ke/v1/dlr' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE' \
--data '{
    "messageId": "9b899e2d-fde0-4361-997b-b802364ff736"
}'

Success Response

{
   "status":true,
   "responseCode":"0200",
   "messages":[
      {
         "phone":"254705xxxxxx",
         "message":"Your Timisha login OTP is 446679 and will expire at 2024-03-11 13:46:06",
         "parts":1,
         "cost":"0.80",
         "sentTime":"2024-03-11 13:41:07",
         "deliveryStatus":{
            "status":"DeliveredToTerminal",
            "deliveryTime":"2024-03-11 13:41:11"
         }
      }
   ]
}

Failed Response

{
    "status": false,
    "responseCode": "0422",
    "message": "No messages found"
}

List of Delivery Statuses

Delivery Status	Description
DELIVRD/Delivered/DeliveredToTerminal	Message successfully delivered to recipient
ACCEPTED	Message accepted by network provider but delivery unknown
EXPIRED	Message took long to be delivered and expired. Occurs when number is unreachable
ENROUTED	The message is currently being delivered and awaiting delivery receipt confirmation from the carrier.
Sent	Message is successfully sent awaiting delivery status
UNDELIV	Failed to deliver
DELETED	The message has failed due to “Barred”, “Absent Subscriber”, or “Delivery Failure”.
UNDELIVERABLE	Message cannot reach recipient
UNKNOWN	No delivery status was received after a specific amount of time therefore delivery is not known
REJECTED	The message was successfully submitted to the carrier for delivery but has actively been refused.
Undelivered	After attempting for a period of time, the carrier has failed to deliver the message to the destination handset. Please confirm the recipient’s number is correct, and the handset is on and within reception range.
BLACKLISTED/SenderName Blacklisted	Promotional message has been blocked by recipient
AbsentSubscriber/Absent Subscriber	Phone number does not exist
DeliveryImpossible/Delivery Impossible	Message cannot be delivered
Network Failure	A network issue has caused delivery failure

f) GET SMS Balance

You can get the SMS balances for both local and international accounts using this end point. It also gives you the local and international accounts numbers used for payments

NOTE: Send a GET request to get balance

Base URL: https://api.timisha.ke/v1/get-balance

Headers

Pass bearer token as the Authorization header. Also include Accept and Content-Type headers as application/json:

Authorization: Bearer Your-api-token_HERE
Accept: application/json
Content-Type: application/json

Json body should be empty

Sample CURL request

curl --location 'https://api.timisha.ke/v1/get-balance' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer Your-api-token_HERE'

Success Response

{
    "status": true,
    "responseCode": "0200",
    "balance": 3245,
    "internationalBalance": 100,
    "localAccountNumber": "testlocal",
    "internationalAccountNumber": "IN-test",
    "emailWhatsAppAccountNumber": "EW-test",
    "walletAccountNumber": "WL-test"
}

Failed Response

{
    "status": false,
    "responseCode": "0401",
    "message": "Unauthenticated"
}

Introduction

Get Phone Number Details

Headers

Json body

Sample CURL request

Success Response

Failed Response

Networks as shown below:

Sending SMS

a) Sending a single SMS

1. JSON POST Request

Headers

Json Body

Sample CURL request

Success Response

Failed Response

2. POST Form Data Request

Success Response

Failed Response

3. GET Request

Success Response

Failed Response

b) Bulk SMS

Headers

Json Body

Sample CURL request

Success Response

Failed Response

c) Personalized Messages

Headers

Json Body

Sample CURL request

Success Response

Failed Response

d) SMS Delivery Status (Callback URL)

e) SMS Delivery Status (Query)

Headers

Json Body

Sample CURL request

Success Response

Failed Response

List of Delivery Statuses

f) GET SMS Balance

Headers

Sample CURL request

Success Response

Failed Response