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.

API-X Gateway


To use the API-X Gateway, you don't need Username and Password. All you need is to create API-X sub-accounts from your main account. A unique API_TOKEN will be generated for every sub-account you create, and you can fund your sub-accounts individually from your main account.

The advantage of our API-X Gateway is that a developer can create and fund different sub-accounts for different projects and applications, so each sub-account details can be tracked independent of other sub-accounts and main account.

You can credit each sub-account by transfering SMS units from your main account to the sub-account.

The following are the possible API-X commands and the corresponding URL. Where,

  • token is the sub-account token generated when a sub-account is created. You can create an API-X (SUB-ACCOUNT) on your dashboard when you log in.
  • cmd value may be send or balance;
  • message 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 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 14:43); 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 Reply
    600: 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://orgds.com.ng/api?cmd=send&message=MESSAGE&recipient=080xxxxxxxx,070xxxxxxxx,090xxxxxxxx&sender=SENDERID&token=APIX_TOKEN&type=0&route=0&schedule=2024-10-12 14:43&display=plain


REPLY: "600" if successfully submitted or an "ERROR_NUMBER" without quotes.


Check Balance (cmd=balance)

http://orgds.com.ng/api?cmd=balance&token=API_TOKEN


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
define('API_TOKEN','xxxxxxxxxxxxxxxxxxxx');
$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://orgds.com.ng/api?cmd=send"
. "sender=".$sender
. "&recipient=".$recipients
. "&message=".$message
. "&token=".API_TOKEN
. "&type=".$type
. "&route=".$route;
. "&display=".$display;

if ($reply = file_get_contents($url)) {
echo $reply;
}
?>

 

Check Balance

?php

$url = "http://orgds.com.ng/api?cmd=balance"
. "&token=".API_TOKEN;

if ($reply = file_get_contents($url)) {
echo $reply;
}
?>

NOTE: You can also use PHP cURL for both POST and GET methods.