SMS API DOCUMENTATION

This is a Hormud REST API for SMS service, the API features include sending SMS, forwarding SMS, and
receiving delivery reports.

URL: https:// smsapi.hormuud.com/

To get started with using HORMUUD SMS API, you would need to register for an account on our
platform (https://business.hormuud.com/).

AUTHENTICATION
Our API accepts Two types of authentication to authorize our clients to interact with and here as follows:

I. Bearer Token

To generate to bearer token you need the follow steps below

API Credentials: username and password, if you don’t have it please register with us on our portal.

Otherwise you can find your credentials under your account profile, it is labeled API PASSWORD.

(https://business.hormuud.com/)

Token Endpoint : https://smsapi.hormuud.com/token

Payload: Should contain the following parameters

Username: Your Username

Password: Your Password

grant type: password (Note: is type of grant please use as it)

Content-Type: application/x-www-form-urlencoded/text

Method Type: POST

Testing Environment

 Example of generating a token on postman

 Send Sms example
Code example: PYTHON

import requests
import datetime
import json

payload = "grant_type=password&username=XXXXXX&password=XXXXXX"
response = requests.request("POST", 'https://smsapi.hormuud.com/token',
data=payload, headers={'content-type': "application/x-www-form-urlencoded"})
Access_Token = json.loads(response.text)
print(Access_Token)

Code example: PHP

$curl = curl_init();
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl,CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_URL, 'https://smsapi.hormuud.com/token');
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query(array('Username' =>
'Username', 'Password' => 'YOUR PASSWORD', 'grant_type' => 'password')));
$ Access_Token = curl_exec($curl)

Code example: C#

HttpClient client = null;

if (client == null)
{
client = new HttpClient
{
BaseAddress = new Uri("https://smsapi.hormuud.com/")
};}
string username = "XXXXXX";
string password = "XXXXXX";
HttpResponseMessage response =
client.PostAsync("Token",new
StringContent(string.Format("grant_type=password&username={0}&password={1}",
HttpUtility.UrlEncode(username),
HttpUtility.UrlEncode(password)), Encoding.UTF8,
"application/x-www-form-urlencoded")).Result;

string resultJSON = response.Content.ReadAsStringAsync().Result;

string Access_Token=
(JObject.Parse(resultJSON).SelectToken("access_token")).ToString();

After all you generate your token then pass it on the Authorization header whenever making requests to
endpoints
Authorization: Bearer <Acess_token >

II. Basic Auth

To access our API, you need the follow the steps below

API Credentials :username and password, if you don’t have it please register with us on our portal
(https://bussiness.hormuud.com/)

Our client should send a HTTP requests with the Authorization header that contains the word Basic word
followed by a space and a base64-encoded string username: password
Authorization: Basic <zx5yyysiswewrw4r==>

Code example: Php

$ch = curl_init(https://smsapi.hormuud.com/api/sms/Send);
$headers = array(
'Content-Type: application/json',
'Authorization: Basic '. base64_encode ("username: password"));

curl_setopt ($ch, CURLOPT_HTTPHEADER,$headers);

curl_setopt ($ch, CURLOPT_HEADER, 1);
curl_setopt ($ch, CURLOPT_USERPWD, $username. ":" . $password);
curl_setopt ($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt ($ch, CURLOPT_RETURNTRANSFER, TRUE);
$return = curl_exec($ch);
curl_close($ch);

OUTBOUND

The outbound SMS is used to send SMS to individual or a group of people by integrating the API in your
application, it can send any SMS by the following endpoints

Endpoints:

This is the endpoint for sending text Message. Our client willing to use Bearer token authorization format
can call this endpoint.

 api/SendSMS :
 api/Outbound/SendSMS

Method-Type: POST

Content-Type: application/json
 Authorization-Type: Bearer Token

 api/sms/Send

Is used to send text Message our client willing to use basic authorization format can call this endpoint

Method-Type: POST.

Content-Type: application/json.

Authorization-Type: Basic Auth.

Request Information
Name Description Type Additional Information
refid It is a reference id from string Optional
end users to refer for
delivery reports
mobile It is the receiver number string Required
of the message
message It is the message content string Required
to be sent
senderid It is the sender/display string Optional
name of the SMS
validity is the validity of the SMS, integer Optional
set it zero as a value if
you don't care

Request Formats

Sample:
{
"refid": "0",
"mobile": "61xxxxxxx",
"message": "test send sms api",
"senderid": "sample string 4",
"validity": 5,
"delivery": 6,
}
Response Formats

Sample:
{
"ResponseCode": "200",
"ResponseMessage": "Success",
"Data": {
"MessageID": "8fa00007d-xxxx-xxx-xxxx-xxxxxxxxx",
"Description": "The message is successfully sent",
"DeliveryCallBack": "https://smsapi.hormuud.com/api/Delivery/GetDelivery?MessageId=8fa00007d-xxxx-xxx-
xxxx-xxxxxxxxx ",

"Details": {
"TextLength": 1,
"TotalCharacters": 2,
"TotalSMS": 3,
"IsGMS7Bit": true,
"ContainsUnicode": true,
"IsMultipart": true,
"ExtensionSet": ["A","A"],
"UnicodeSet": ["A","A"],
"MessageParts": [ "sample string 1","sample string 2"] }
}
}
DELIVERY REPORT

For the delivery report there is some steps that are required to register on our portal

url: this is the call back url that we will push the delivery report. (https:// yoururl.com/delivery report?)
Parameters to accept:

Parameters Details
MessageID The message Id of the received Delivery Report
Origin The Sender ID of the Message
Destination The Receiver of the Message
Message The Content of Delivery Information
DLRStatus The Status of Message is sent
DLRTime The Delivery Time of the Message

Method: Here you required to provide your method type whether is POST/GET

Note

You can have your own custom parameter names.

INBOUND

For the Incoming sms there is some steps that are required to register on our portal

url: this is the call back url that we will push the delivery report. (https:// yoururl.com/receive?)
Parameters to accept:

Parameters Details
Sender Mobile number sent a message
MessageText The content of the message was sent
ShortCode The number that receives the message
TimeSent The time the message was sent

Method: Here you required to provide your method type whether is POST/GET

Note

You can have your own custom parameter names.

RESPOND CODES

Code(s) Details

200 SUCCESS
201 Authentication Failed
203 Invalid Sender ID
204 Zero Balance (Prepaid Account)
205 Insufficient Balance (Prepaid Account)
206 The allowed message parts are exceeded
207 Wrong mobile number
500 Unknown Error