OrgDS offers simple and easy-to-integrate SMS connectivity for system application and web developers. With our Application Programming Interface (API), integration is simple, fast and reliable. Our API allows developers to connect to our website from Desktop, Mobile and Web Applications to send messages, check sent messages, and check SMS balance. Although for account security issues, we recommend sending data to OrgDS API via POST method, we accept both POST and GET methods.
We have two categories of API: API-N and API-X.
API-N Gateway
API-N provides a direct connection to a user's account. It requires the Username and Password of the user to connect and execute all the possible commands.
The following are the possible API-NORMAL commands and the corresponding URL. Where,
- username is the Developer's main account login username;
- password is the Developer's main account login password;
- cmd value may be send or balance;
- message: This variable is applicable when sending message. It is the message you are sending to one or more recipients;
- recipient: This variable is applicable only when sending message. It is the phone number of a recipient or a list of comma delimited phone numbers of recipients of the message.
- sender: This variable is applicable only when sending message. It is the SHORT ID/NAME of the Sender with which recipients will receive the message. SENDERID must not be longer than 11 characters. If no SENDERID is set, your default Sender ID as set on your profile or APIX account will be used.
- type (optional) Message type value may be either 0 or 1.
This variable is applicable only when sending message.
0=Normal Text Message that will be saved automatically in the recipient's inbox. This (value 0) is the default value if no the variable is not set or set with unknown value.
1=Flash Message that will just appear on recipient's screen. - route (optional, Default is 1) value may be 0 (Basic), 1 (BasicPlus), 2 (Corporate), 5 (SIM Server), or 6 (SIM Server Plus).
This variable is applicable only when sending message.
0 (Basic Route) Your message will be sent via Basic Route. When Basic Route is used, phone numbers on DND (Do Not Disturb) will not receive the message and are not charged.
1 (Basic Plus): Your message will be sent via Basic Route but sent to only DND numbers via Corporate Route (DND numbers are charged at 1.7 units/SMS Page).This (value 1) is the default value if the variable is not set or set with unknown value.
2 (Corporate Route): All messages will be sent via Corporate Route. When Corporate Route is used, recipients on DND will receive the message but you will be charged 1.7 units for each page of the message.
5 (SIM Server): DND numbers will be filtered, but only numbers on DND will receive your message via one of our dedicated SIM servers at 1.7 units for each page of the message.
6 (SIM Server Plus): Your message will be sent to all recipients via SIM server at 1.7 units for each page of the message. - schedule (optional)
This variable is applicable only when sending message. It allows you to set a future date and time (not less than 3 minutes) when you want a message to be delivered to specified recipiet(s). The date and time value must be in the YYYY-MM-DD HH:MM format (e.g. 2024-10-12 23:51); the time should be in 24 hour format. If not set, the message will be submitted for immediate delivery. - display (optional)
The 'display' variable is an optional variable, applicable only when sending message (not applicable when scheduling). It allows a developer to specify the display format of the success reply that will be displayed after a message is sent. The value can be 'plain', 'xml', or 'json'. The default is 'simdple'.The plain [
display=plain
] value will display a plain text reply that shows a number and a message.
Plain Reply600: Message sent/scheduled successfully
An xml [
display=xml
] reply will display XML-formatted details of the response.
XML Reply
A json [
display=json
] reply will display json-formatted details of the response.
JSON Reply
Send SMS (cmd=send)
http://www.orgds.com.ng/api?username=XXXXXXXX&password=XXXXXXXX&cmd=send&message=MESSAGE&recipient=23480xxxxxxxx,23470xxxxxxxx,23490xxxxxxxx&sender=SENDERID&type=0&route=0&schedule=2024-10-12 23:51&display=plain
REPLY: "600" if successfully submitted or an "ERROR_NUMBER" without quotes.
Check Balance (cmd=balance)
http://www.orgds.com.ng/api?username=XXXXXXXX&password=XXXXXXXX&cmd=balance
REPLY: "THE_NUMERICAL_BALANCE" or an "ERROR_NUMBER" without quotes.
POSSIBLE REPLIES AND ERROR NUMBERS
SUCCESS REPLIES
600: Message sent/scheduled successfully
0.00: SMS Balance
ERROR REPLIES
700: Required parameter/variable is missing
701: Username is empty
702: Password is empty
703: Unexpected error
704: Unknown command
705: Unable to connect
706: Wrong access credentials
707: Message is empty
708: Recipient is empty
709: Insufficient balance
710: Incorrect schedule date format. Accepted format is YYYY-MM-DD HH:MM
711: Token is empty
712: Sender ID is empty
713: Account is not active
714: Unable to send message
715: Schedule time is less than 5 minutes ahead
HOW TO USE THE API
PHP, ASP, JSP and other developers can transfer urlencoded data to both API-NORMAL and API-X URLs via GET or POST method. The following are PHP examples of how to send SMS and check BALANCE via GET method, with PHP file_get_contents() function.
Send SMS
?php
$username = urlencode($_REQUEST['username']);
$password = urlencode($_REQUEST['password']);
$message = urlencode($_REQUEST['message']);
$recipients = urlencode($_REQUEST['recipients']);
$sender = urlencode($_REQUEST['sender']);
$type = urlencode($_REQUEST['type']);
$route = urlencode($_REQUEST['route']);
$display = urlencode($_REQUEST['display']);
$url = "http://www.orgds.com.ng/api?cmd=send"
. "sender=".$sender
. "&recipient=".$recipients
. "&message=".$message
. "&username=".$username
. "&password=".$password
. "&type=".$type
. "&route=".$route;
. "&display=".$display;
if ($reply = file_get_contents($url)) {
echo $reply;
}
?>
Check Balance
?php
$username = urlencode($_REQUEST['username']);
$password = urlencode($_REQUEST['password']);
$url = "http://www.orgds.com.ng/api?cmd=balance"
. "&username=".$username
. "&password=".$password
if ($reply = file_get_contents($url)) {
echo $reply;
}
?>
NOTE: You can also use PHP cURL for both POST and GET methods.
Learn about API-X»
Download Sample Script»
Go to Developers' API Documentation»