API REFERENCE VERSION 3.0

Introducing our new API V3 that is developed to enhance your messaging experience with reduced complexity.

Overview

This User Manual provides specifications of the API for the automated sending of SMS via the Internet. This guide is intended for the developers and clients alike who plan to integrate their systems with Bulk SMS service.

Required Environment

In order to use our API, you will need to have a system that has internet connectivity. This may be direct internet connectivity or via a firewall or proxy server. Additionally, should you wish to receive delivery reports (DLRs), you must have a web server that is able to receive incoming requests from the Internet. This web server does not necessarily have to be running on the same machine that is sending messages to us.

This is one of the simpler server-based method of communication. It can be used either in the form of a HTTP POST or HTTP GET. We recommend POST for larger data transfer and data security. All calls to the API must be URL-encoded. The parameter names are case sensitive.

Note: We recommend POST for larger data transfer and data security. All calls to the API must be URL encoded.

SSL Enabled API Triggering

This API has been designed to allow you to access it using an SSL Enabled connection for added security.

To trigger the API on an SSL enabled connection, enter the URL beginning with https:// instead of http://

Mobile Phone Number Format

All mobile phone numbers submitted via API should be a valid 10 digit mobile number starting from 7, 8 or 9. For example: 9xxxxxxxxx, 8xxxxxxxxx, 7xxxxxxxxx.If mobile number exceeds 10 digits the last 10 digits will be considered as a mobile number. For example: 919xxxxxxxxx will be considered as 9xxxxxxxxx

Security

Our API supports both HTTP and HTTPS. Using HTTPS to encrypt all requests through SSL is recommended, but if you're using a client and tool that's not set up to make SSL requests, you can use HTTP. All requests are secured through BASIC authentication via the Working Key. An additional level of protection is provided where Working key can be configured to accept requests from a specific IP Address only. Also, API usage with username & password combination is removed due to security concerns.

Output Restrictions

If the provider network is down, our Gateway Servers will retry your message up to six hours before giving up. Also, Duplicate messages in single request only are filtered by default. A "duplicate message" is defined as the same destination address, sender address and the message body. However, duplicate messages sent by different request are NOT filtered.

Input Restrictions

All the parameter passed must be provided in the URL encoded format. Also, recommended to use the POST method for error free submission due to URL limitations.

Sender ID Options

All text messages carry a sender ID. When you send a text message through API, you could use any of the approved sender IDs for your account. You can reach us for applying for a new sender ID.

Setting a Sender ID (Alphabetic Originator)

You can set the sender ID with your company name, or anything. So, this means that your recipients could see the name you want in the sender field rather than just a phone number. This alphabetic originator, or sender ID, can contain characters from a-z, A-Z. Other characters may cause messages to fail.

Supported Character Sets

GSM 03.38 Encoding

The standard SMS mobile-phone character set is used universally to send text messages. The standard character set allows few of the Roman alphabet and the most common accented forms, certain special characters, and few Greek alphabets that sum up to 160 characters. It includes the following characters:

@ £ \ $ ¥ è é ù ì ò Ç \ n Ø ø \ r Å å ? _ F " ? O ? ? S T ? Æ æ ß É ! \ " # ¤ % & ' ( ) * + , - ../ 0 1 2 3 4 5 6 7 8 9 : ; < = > ? ¡ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z ? Ö Ñ Ü § ¿ a b c d e f g h I j k l m n o p q r s t u v w x y z ö ñ ü à ä Ä { } \ ~ [ ]

Note: All extended characters will take two characters to send. Extended characters are: £ ¥ è é ù ì ò Ç Ø ø Å å Δ Φ Γ Λ Ω Π Ψ Σ Θ Ξ Æ æ ß É ¤ ¡ Ä Ö Ñ Ü § ¿ ä ö ñ ü à | \ { } ~ [ ] ^ Also, extended character like € takes three characters to send.

Unicode

When using non-GSM 03.38 characters SMS transmits as a Unicode message. The Unicode character support provides the ability to send a message in Hindi, Kannada, Tamil etc.

If the message to be transmitted is in Unicode format, the entire message has to be converted into Unicode. Also, Unicode transmission will charge double the credits, including plain English SMS sent in Unicode mode.

Message Length - Multipart Messages

Standard GSM 03.38 Character Set

Single text messages are limited to 160 characters, including spaces. The maximum length of two-part or three-part multipart text messages is 306 (2 x 153) and 459 (3 x 153) characters, respectively. You could send up to 1000 characters as multipart message which will be split into 7 messages internally. This refers only to messages that contain the standard GSM 03.38 character set.Each multipart text message is limited to 153 characters rather than 160 due to the need for user-data headers (UDHs) information. Mobile phones use UDH information to enable them to link long messages together so that they appear as single SMS messages in recipient’s phone inbox.

Number of SMS Number of characters in the linked SMS
1 upto 160 characters
2 upto 306 characters (2 x 153)
3 upto 459 characters (3 x 153)
4 upto 612 characters (4 x 153)
5 upto 765 characters (5 x 153)
6 upto 918 characters (6 x 153)
7 upto 1000 characters (6 x 153) + (1 x 82)

Unicode Characters

Using Unicode, for languages such as Hindi, restricts your message to a maximum of 70 characters per SMS. You can, however, send longer text messages, with our system splitting them into two or at the three separate text messages. The maximum lengths of two-part and three-part multipart Unicode text messages are 134 (2 x 67) and 201 (3 x 67) characters, respectively. You could send up to 500 characters as multipart message which will be split into 8 messages internally.

Number of SMS Number of characters in the linked SMS
1 upto 70 characters
2 upto 134 characters (2 x 67)
3 upto 201 characters (3 x 67)
4 upto 268 characters (4 x 67)
5 upto 335 characters (5 x 67)
6 upto 402 characters (6 x 67)
7 upto 469 characters (7 x 67)
8 upto 500 characters (7 x 67) + (1 x 31)

Successful Submission of SMS

For each successful submission of an SMS, the API would return a unique message ID for that transaction. The Client’s Application should capture the unique message ID and fetch a Delivery Report (DLR) against that corresponding message ID. This message ID then can be used to track the status of the message and receive the delivery report against this message ID through the delivery report URL specified by the client.

Response Formats

By default, the API URL generates responses in JSON format. You can also generate responses in XML, PHP, JSONP formats. All you need to do is add &format=php (for PHP format) or &format=xml (for XML format).

Response Parameters

The response parameters in case of error in API are tabulated below:

Name Parameter Description Expected Values
Response code status Error code for your api call Numeric Value A401, E601 etc
Error Message Message Error Message for API call String.Refer API Error codes section

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the API in the below format are :

STATUS MESSAGE
A400 Api file not found in project
A401A Method Not Implemented.
A401B Method Not Found
A402 Api Key not found.
A403 Api Signature not found
A404 Your api account got suspended
A405 Api secret not found.
A406 Request is not allowed from this ip
A407 Header misconfigured
A408 Api Signature not equal

SMS Status Codes-HTTP API(On Submission)

When we receive an API call for sending SMS one of the following status code is attached at the application level. However, operator level status codes are tabulated next.

The common status codes received while using the API are:

AWAITED-DLR Mobile number has been accepted and submitted to the operator. Awaiting delivery report from the operator
DNDNUMB Mobile number is DND.
A401B Method Not Found
OPTOUT-REJ Optout from subscription.
INVALID-NUM In case any invalid number present along with the valid numbers.

SMS Status Codes-XML/JSON API(On Submission)

There could be one or more nodes in an XML API, each of those nodes could have a different status code on submission

The common status codes received while using the API are:

AWAITED-DLR Mobile number has been accepted and submitted to the operator. Awaiting delivery report from the operator
DNDNUMB Mobile number is DND.
A401B Method Not Found
OPTOUT-REJ Optout from subscription.
INVALID-NUM In case any invalid number present along with the valid numbers.
SENDER-ID-NOT-FOUND In case the sender ID given in any one of the nodes is not available
INV-TEMPLATE-MATCH In case the message given in any one of the nodes does not match the template approved for the sender ID in the same node
MAX-LENGTH In case the message given in any one of the nodes exceeds the maximum of 1000 characters

SMS Status Codes(Operator Level)

On submission of a message to operator, we associate one of the following status codes to every SMS in order to track the status

The common status codes received while using the API are

NO-CREDITS Insufficient credits.
SERIES-BLOCK Mobile number series blocked.
INV-NUMBER Invalid number.
SERVER-ERR Server error
SPAM Spam SMS
SNDRID-NOT-ALLOTED Sender ID not allocated
BLACKLIST Blacklisted number
TEMPLATE-NOT-FOUND Template not mapped.
INV-TEMPLATE-MATCH Template not matching approved text.
SENDER-ID-NOT-FOUND Sender ID not found.
DNDNUMB DND registered number.
NOT-OPTIN Not subscribed for opt-in group.
TIME-OUT-PROM Time out for promotional SMS.
DELIVRD SMS successfully delivered.
INVALID-SUB Number does not exist. / Failed to locate the number in HLR database.
ABSENT-SUB Telecom services not providing service for the particular number. / Mobile Subscriber not reachable.
HANDSET-ERR Problem with Handset or handset failed to get the complete message. / Handset doesn’t support the incoming messages.
BARRED End user has enabled message barring system. / Subscriber only accepts messages from Closed User Group [CUG].
NET-ERR Subscriber’s operator not supported. / Gateway mobile switching error.
MEMEXEC Handset memory full.
FAILED SMS expired due to roaming limitation. / Failed to process the message at operator level.
MOB-OFF Mobile handset in switched off mode.
HANDSET-BUSY Subscriber is in busy condition.
SERIES-BLK Series blocked by the operator.
EXPIRED SMS expired after multiple re-try.
REJECTED SMS Rejected as the number is blacklisted by operator.
OUTPUT-REJ Unsubscribed from the group.
REJECTED-MULTIPART Validation fail [SMS over 160 characters]
UNDELIV Failed due to network errors.
NO_DLR_OPTR In case operator have not acknowledge on status report of the SMS.

Sending An SMS

HTTP API sends a text message using POST/GET and form-encoded data. The URL you use to send a text message has a required field called api_key, which is unique and assigned to your account.

The other required parameters for the Request are method,sender, to and message, which are used to define the destination phone number and the message body. If you want to send to multiple phone numbers, provide the numbers in comma separated format.

To send an SMS using the HTTP API, the following URL format is used:
http://URL/api/v3/index.php?method=sms&api_key=Ad9e5XXXXXXXXXXXXX&to=997XXXXXXX,997XXXXXXX&sender=INFXXX&message=testing&
format=json&custom=1,2&flash=0

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method sms
API/Working key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
Sender ID sender Sender ID assigned to your account Sender ID
Mobile number to Mobile number to which the SMS is to be sent.The destination mobile number can be with or without 91. Also provide multiple numbers in comma separated format. Mobile number(GET-10numbers,POST-100numbers)
Message message Message to be sent Message text which is URL encoded(1000 char for normal, 500 for unicode)

Optional Parameters

The optional parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
delivery reports URL dlrurl The URL to receive delivery reports. Spiffing custom is mandatory. delivery reports URL
Message ID custom Custom message ID by customer, comma separated Alphanumeric (max 40 char)
Schedule time time Date and time for scheduling an SMS EX Format: YYYY-MM-DD HH:MM:SS OR YYYY-MM-DD HH:MM AM/PM
unicode unicode To specify that the message to be sent is in unicode format. Also can be used for automatic detection of unicode SMS. 1 / 0 / auto
flash flash To specify that the message is to be sent in the flash format 1 or 0

Advanced Parameters(Optional)

The advanced parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON
Callback function name callback Callback function for JSONP response format String
unicode character unicodechar Choose what to do if message contains Unicode character Reject(default) or sendunicode
Custom reference fields custom1 & custom2 Custom reference fields Alphanumeric (max 40 char)
port number port Port number to which SMS has to be sent Valid integer port number above 2000

Example Responses

<api>
  <status>OK</status>
  <data>
    <group_id>2758</group_id>
    <sms>
      <id>2758-1</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
{if $config.service_key eq 'global'}      <country>IN</country>
{/if}
    </sms>
    <sms>
      <id>2758-2</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
{if $config.service_key eq 'global'}      <country>IN</country>
{/if}
    </sms>
      ...
  </data>
  <message>Campaign of 2 numbers Submitted successfully.</message>
</api>
{
    "status": "OK",
    "data": 
    {
        "group_id":2758,
        "0":
        {
            "id": "2758-1",
            "customid": "1",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
			}         
           "1":
        	{
            "id": "2758-2",
            "customid": "2",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
			}            
          }
            ...
    }
    "message": "Campaign Submitted successfully"
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [data] => Array
        (
            [group_id] => 2758
            [0] => Array
                (
                    [id] => 2758-6
                    [customid] => 1
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
              {if $config.service_key eq 'global'}      [country] => IN
              {/if}
  )
            [1] => Array
                (
                    [id] => 2758-7
                    [customid] => 2
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
              {if $config.service_key eq 'global'}      [country] => IN
              {/if}
  )                    
             ...
        )
    [message] => Campaign Submitted successfully
)
{
    "status":"A404",
    "message":"Your api account got suspended"
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.
group_id Website group id for your reference
data All the response is wrapped in side data
sms Each number will be wrapped inside sms
id Website message id for your reference
customid Custom message id if you provide one
customid1 Custom message id 1 if you provide one
customid2 Custom message id 2 if you provide one
mobile Mobile number the sms will be sent
status status of the message

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the API to send an SMS is in the below format:

STATUS MESSAGE
A411 Port number must be numeric
A415 Invalid xml/Invalid Json
A416 Invalid Message ID/Mobile
A417 Invalid Message ID/Mobile
A418 Invalid Group ID/Campaign
A419 Invalid Group ID/Campaign
A430 Invalid Group ID
A431 Invalid Group ID
A432 Campaign already completed/Campaign already cancelled
A433 Schedule time already passed
A434 Campaign within next 15 minutes cannot be modified/canceled.
A434 Invalid schedule time. Minimum 15 min time gap is required.
E601 Missing receipent
E603 Missing message
E602 Missing senderid
E604 Senderid must be less than 14 chars
E605 Invalid Sender or Sender not allowed
E606 Invalid schedule time. Minimum 15 min time gap is required.
E606A Batch size should be greater or equal to 1000
E606B Schedule minute should be in multiples of 15. minimum 15 minute
E612 Invalid Template Matched
E607 SMS length is exceeding 1000 characters
E607A Unable to find gateway to sent sms.
E608 No Valid mobile numbers found
E608A Your daily usage limit exceeded
E609 An error occured while saving group details
E610 Unable to write to temp files
E611 Unable to process your request. try again
H601 Insufficent credits. Total 1. Required 1 more credits.

Sending a Unicode SMS

To send a unicode SMS using the HTTP API, the following URL format is used:

http://URL/api/v3/index.php?method=sms&api_key=Ad9e5XXXXXXXXXXXXX&to=997XXXXXXX,997XXXXXXX&sender=INFXXX&message=testing
&unicode=1

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method sms
API/Working key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
Sender ID sender Sender ID assigned to your account Sender ID
Mobile number to Mobile number to which the SMS is to be sent.The destination mobile number can be with or without 91. Also provide multiple numbers in comma separated format. Mobile number(GET-10 numbers, POST-100 numbers)
Message message Message to be sent Message text which is URL encoded(1000 char for normal, 500 for unicode)
unicode unicode To specify that the message to be sent is in unicode format. Also can be used for automatic detection of unicode SMS. 1 / 0 / auto

Optional Parameters

The optional parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
delivery reports URL dlrurl The URL to receive delivery reports. Spiffing custom is mandatory. delivery reports URL
Message ID custom Custom message ID by customer, comma separated Alphanumeric (max 40 char)
Schedule time time Date and time for scheduling an SMS EX Format: YYYY-MM-DD HH:MM:SS OR YYYY-MM-DD HH:MM AM/PM
flash flash To specify that the message is to be sent in the flash format 1 or 0

Advanced Parameters(Optional)

The advanced parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON
Callback function name callback Callback function for JSONP response format String
unicode character unicodechar Choose what to do if message contains Unicode character Reject(default) or sendunicode
Custom reference fields custom1 & custom2 Custom reference fields Alphanumeric (max 40 char)
port number port Port number to which SMS has to be sent Valid integer port number above 2000

Example Responses

<api>
  <status>OK</status>
  <data>
    <group_id>2758</group_id>
    <sms>
      <id>2758-1</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
    </sms>
    <sms>
      <id>2758-2</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
    </sms>
      ...
  </data>
  <message>Campaign of 2 numbers Submitted successfully.</message>
</api>
{
    "status": "OK",
    "data": 
    {
        "group_id":2758,
        "0":
        {
            "id": "2758-1",
            "customid": "1",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
		},
        "1":
        {
            "id": "2758-2",
            "customid": "2",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
			}          
            ...
    	}
    "message": "Campaign Submitted successfully"
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [data] => Array
        (
            [group_id] => 2758
            [0] => Array
                (
                    [id] => 2758-6
                    [customid] => 1
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
  				)
            [1] => Array
                (
                    [id] => 2758-7
                    [customid] => 2
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
  				)                    
             ...
        )
    [message] => Campaign Submitted successfully
)
{
    "status":"A404",
    "message":"Your api account got suspended"
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.
group_id Website group id for your reference
data All the response is wrapped in side data
sms Each number will be wrapped inside sms
id Website message id for your reference
customid Custom message id if you provide one
customid1 Custom message id 1 if you provide one
customid2 Custom message id 2 if you provide one
mobile Mobile number the sms will be sent
status status of the message

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the API to send an SMS is in the below format :

Status Message
A411 Port number must be numeric
A415 Invalid xml/Invalid Json
A416 Invalid Message ID/Mobile
A417 Invalid Message ID/Mobile
A418 Invalid Group ID/Campaign
A419 Invalid Group ID/Campaign
A430 Invalid Group ID
A431 Invalid Group ID
A432 Campaign already completed/Campaign already cancelled
A433 Schedule time already passed
A434 Campaign within next 15 minutes cannot be modified/canceled.
A434 Invalid schedule time. Minimum 15 min time gap is required.
E601 Missing receipent
E603 Missing message
E602 Missing senderid
E604 Senderid must be less than 14 chars
E605 Invalid Sender or Sender not allowed
E606 Invalid schedule time. Minimum 15 min time gap is required.
E606A Batch size should be greater or equal to 1000
E606B Schedule minute should be in multiples of 15. minimum 15 minute
E612 Invalid Template Matched
E607 SMS length is exceeding 1000 characters
E607A Unable to find gateway to sent sms.
E608 No Valid mobile numbers found
E608A Your daily usage limit exceeded
E609 An error occured while saving group details
E610 Unable to write to temp files
E611 Unable to process your request. try again
H601 Insufficent credits. Total 1. Required 1 more credits.

Scheduling SMS

To schedule an SMS using the HTTP API, the following URL format is used:

http://URL/api/v3/index.php?method=sms&api_key=Ad9e5XXXXXXXXXXXXX&to=997XXXXXXX,997XXXXXXX&sender=INFXXX&message=testing&
time=2014-08-26 04:45pm

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method sms
API/Working key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
Sender ID sender Sender ID assigned to your account Sender ID
Mobile number to Mobile number to which the SMS is to be sent.The destination mobile number can be with or without 91. Also provide multiple numbers in comma separated format. Mobile number(GET-10numbers,POST-100numbers)
Message message Message to be sent Message text which is URL encoded(1000 char for normal, 500 for unicode)
Schedule time time Date and time for scheduling an SMS EX Format: YYYY-MM-DD HH:MM:SS OR YYYY-MM-DD HH:MM AM/PM

Optional Parameters

The optional parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
delivery reports URL dlrurl The URL to receive delivery reports. Spiffing custom is mandatory. delivery reports URL
Message ID custom Custom message ID by customer, comma separated Alphanumeric (max 40 char)
unicode unicode To specify that the message to be sent is in unicode format. Also can be used for automatic detection of unicode SMS. 1 / 0 / auto
flash flash To specify that the message is to be sent in the flash format 1 or 0

Advanced Parameters(Optional)

The advanced parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON
Callback function name callback Callback function for JSONP response format String
unicode character unicodechar Choose what to do if message contains Unicode character Reject(default) or sendunicode
Custom reference fields custom1 & custom2 Custom reference fields Alphanumeric (max 40 char)
port number port Port number to which SMS has to be sent Valid integer port number above 2000

Example Responses

<api>
  <status>OK</status>
  <data>
    <group_id>2758</group_id>
    <sms>
      <id>2758-1</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
    </sms>
    <sms>
      <id>2758-2</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
    </sms>
      ...
  </data>
  <message>Campaign of 2 numbers Submitted successfully.</message>
</api>
{
    "status": "OK",
    "data": 
    {
        "group_id":2758,
        "0":
        {
            "id": "2758-1",
            "customid": "1",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
     		},
        	"1":
        	{
            "id": "2758-2",
            "customid": "2",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
			}
            ...
    	}
    "message": "Campaign Submitted successfully"
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [data] => Array
        (
            [group_id] => 2758
            [0] => Array
                (
                    [id] => 2758-6
                    [customid] => 1
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
  )
            [1] => Array
                (
                    [id] => 2758-7
                    [customid] => 2
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
  )                    
             ...
        )
    [message] => Campaign Submitted successfully
)
{
    "status":"E606",
    "message":"Invalid schedule time. Minimum 15 min time gap is required."
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.
group_id Website group id for your reference
data All the response is wrapped in side data
sms Each number will be wrapped inside sms
id Website message id for your reference
customid Custom message id if you provide one
customid1 Custom message id 1 if you provide one
customid2 Custom message id 2 if you provide one
mobile Mobile number the sms will be sent
status status of the message

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the API to send an SMS is in the below format:

Status Message
A411 Port number must be numeric
A415 Invalid xml/Invalid Json
A416 Invalid Message ID/Mobile
A417 Invalid Message ID/Mobile
A418 Invalid Group ID/Campaign
A419 Invalid Group ID/Campaign
A430 Invalid Group ID
A431 Invalid Group ID
A432 Campaign already completed/Campaign already cancelled
A433 Schedule time already passed
A434 Campaign within next 15 minutes cannot be modified/canceled.
A434 Invalid schedule time. Minimum 15 min time gap is required.
E601 Missing receipent
E603 Missing message
E602 Missing senderid
E604 Senderid must be less than 14 chars
E605 Invalid Sender or Sender not allowed
E606 Invalid schedule time. Minimum 15 min time gap is required.
E606A Batch size should be greater or equal to 1000
E606B Schedule minute should be in multiples of 15. minimum 15 minute
E612 Invalid Template Matched
E607 SMS length is exceeding 1000 characters
E607A Unable to find gateway to sent sms.
E608 No Valid mobile numbers found
E608A Your daily usage limit exceeded
E609 An error occured while saving group details
E610 Unable to write to temp files
E611 Unable to process your request. try again
H601 Insufficent credits. Total 1. Required 1 more credits.

Sending SMS To An Optin Group

The URL for sending an SMS to an optin group is in the following format:

http://URL/api/v3/index.php?method=optin&api_key=Ad9e5XXXXXXXXXXXXX&sender=INFXXX&message=testing&format=json&name=keyword777

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method optin
API/Working key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
Sender ID sender Sender ID assigned to your account Sender ID
ID or keyword id/name id-optin group ID/name-Optin keyword comma seperated id or optin group keyword
Message message Message to be sent Message text which is URL encoded(1000 char for normal, 500 for unicode)

Optional Parameters

The optional parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
Schedule time time Date and time for scheduling an SMS EX Format: YYYY-MM-DD HH:MM:SS OR YYYY-MM-DD HH:MM AM/PM
unicode unicode To specify that the message to be sent is in unicode format. Also can be used for automatic detection of unicode SMS. 1 / 0 / auto
flash flash To specify that the message is to be sent in the flash format 1 or 0
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON
Callback function name callback Callback function for JSONP response format String

Example Responses

<api>
  <status>OK</status>
  <data>
    <group_id>2758</group_id>
    <optin>
      <id>2758-1</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
    </optin>
    <optin>
      <id>2758-2</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
    </optin>
      ...
  </data>
  <message>Campaign of 2 numbers Submitted successfully.</message>
</api>
{
    "status": "OK",
    "data": 
    {
        "group_id":2758,
        "0":
        {
            "id": "2758-1",
            "customid": "1",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
        },
        "1":
        {
            "id": "2758-2",
            "customid": "2",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
			}        
            ...
    	}
    "message": "Campaign Submitted successfully"
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [data] => Array
        (
            [group_id] => 2758
            [0] => Array
                (
                    [id] => 2758-6
                    [customid] => 1
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
  )
            [1] => Array
                (
                    [id] => 2758-7
                    [customid] => 2
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
 )                    
             ...
        )
    [message] => Campaign Submitted successfully
)
{
    "status":"A404",
    "message":"Your api account got suspended"
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.
group_id Website group id for your reference
data All the response is wrapped in side data
optin Each number will be wrapped inside optin
id Website message id for your reference
customid Custom message id if you provide one
customid1 Custom message id 1 if you provide one
customid2 Custom message id 2 if you provide one
mobile Mobile number the sms will be sent
status status of the message

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the Optin API to send an SMS is in the below format:

Status Message
A430 Group name/id missing
A431 Group is empty
A432 Invalid mobile number
A433 Keyword name/number missing
A434 Keyword not found
A435 Keyword is not active
A436 No sender found!
H601 Insufficent credits. Total 1. Required 1 more credits.

Sending A Port SMS

Using the below API we can send a normal or unicode SMS to a particular port
Application port numbers can be used in SMS messages to deliver a particular SMS to an application on a mobile phone.
If any application is present and running in that particular port, the text is received as port SMS else the message will hit the native inbox of the mobile

NOTE:The API tries to hit the application(port) for 10 seconds, if unsuccessful the message is delivered on the native inbox

To send a port SMS using the HTTP API, the following URL format is used:

http://URL/api/v3/index.php?method=sms&api_key=Ad9e5XXXXXXXXXXXXX&to=997XXXXXXX,997XXXXXXX&sender=INFXXX&message=testing&
format=json&port=8090

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method sms
API/Working key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
Sender ID sender Sender ID assigned to your account Sender ID
Mobile number to Mobile number to which the SMS is to be sent.The destination mobile number can be with or without 91. Also provide multiple numbers in comma separated format. Mobile number(GET-10numbers,POST-100numbers)
Message message Message to be sent Message text which is URL encoded(1000 char for normal, 500 for unicode)
Port Number port Port number to which SMS has to be sent Valid integer port number above 2000

Optional Parameters

Name Parameter Description Expected Values
delivery reports URL dlrurl The URL to receive delivery reports. Spiffing custom is mandatory. delivery reports URL
Message ID custom Custom message ID by customer, comma separated Alphanumeric (max 40 char)
Schedule time time Date and time for scheduling an SMS EX Format: YYYY-MM-DD HH:MM:SS OR YYYY-MM-DD HH:MM AM/PM
unicode unicode To specify that the message to be sent is in unicode format. Also can be used for automatic detection of unicode SMS. 1 / 0 / auto
flash flash To specify that the message is to be sent in the flash format 1 or 0

Advanced Parameters(Optional)

Name Parameter Description Expected Values
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON
Callback function name callback Callback function for JSONP response format String
unicode character unicodechar Choose what to do if message contains Unicode character Reject(default) or sendunicode
Custom reference fields custom1 & custom2 Custom reference fields Alphanumeric (max 40 char)
port number port Port number to which SMS has to be sent Valid integer port number above 2000

Message Length - Multipart Port Messages

Standard GSM 03.38 Character Set

You could send up to 1000 characters as multipart message which will be split into 7 messages internally.

Number of SMS Number of characters in the linked SMS
1 146 characters
2 292 characters (2 x 146)
3 438 characters (3 x 146)
... ..
7 1000 characters (6 x 146) + 124

Unicode

You could send up to 500 characters as multipart message which will be split into 8 messages internally.

Number of SMS Number of characters in the linked SMS
1 64 characters
2 128 characters (2 x 64)
3 192 characters (3 x 64)
... ..
8 500 characters (7 x 64) + 52

Example Responses

<api>
  <status>OK</status>
  <data>
    <group_id>2758</group_id>
    <sms>
      <id>2758-1</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
    </sms>
    <sms>
      <id>2758-2</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
    </sms>
      ...
  </data>
  <message>Campaign of 2 numbers Submitted successfully.</message>
</api>
{
    "status": "OK",
    "data": 
    {
        "group_id":2758,
        "0":
        {
            "id": "2758-1",
            "customid": "1",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
			},
        	"1":
        	{
            "id": "2758-2",
            "customid": "2",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
			}
            ...
    }
    "message": "Campaign Submitted successfully"
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [data] => Array
        (
            [group_id] => 2758
            [0] => Array
                (
                    [id] => 2758-6
                    [customid] => 1
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
  )
            [1] => Array
                (
                    [id] => 2758-7
                    [customid] => 2
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
  )                    
             ...
        )
    [message] => Campaign Submitted successfully
)
{
    "status":"A404",
    "message":"Your api account got suspended"
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.
group_id Website group id for your reference
data All the response is wrapped in side data
sms Each number will be wrapped inside sms
id Website message id for your reference
customid Custom message id if you provide one
customid1 Custom message id 1 if you provide one
customid2 Custom message id 2 if you provide one
mobile Mobile number the sms will be sent
status status of the message

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the API to send an SMS is in the below format :

Status Message
A411 Port number must be numeric
A415 Invalid xml/Invalid Json
A416 Invalid Message ID/Mobile
A417 Invalid Message ID/Mobile
A418 Invalid Group ID/Campaign
A419 Invalid Group ID/Campaign
A430 Invalid Group ID
A431 Invalid Group ID
A432 Campaign already completed/Campaign already cancelled
A433 Schedule time already passed
A434 Campaign within next 15 minutes cannot be modified/canceled.
A434 Invalid schedule time. Minimum 15 min time gap is required.
E601 Missing receipent
E603 Missing message
E602 Missing senderid
E604 Senderid must be less than 14 chars
E605 Invalid Sender or Sender not allowed
E606 Invalid schedule time. Minimum 15 min time gap is required.
E606A Batch size should be greater or equal to 1000
E606B Schedule minute should be in multiples of 15. minimum 15 minute
E612 Invalid Template Matched
E607 SMS length is exceeding 1000 characters
E607A Unable to find gateway to sent sms.
E608 No Valid mobile numbers found
E608A Your daily usage limit exceeded
E609 An error occured while saving group details
E610 Unable to write to temp files
E611 Unable to process your request. try again
H601 Insufficent credits. Total 1. Required 1 more credits.

Adding Contacts to a group

The URL for adding contacts to a group is in the following format:

http://URL/api/v3/index.php?method=groups.register&api_key=Ad9e5XXXXXXXXXXXXX&name=friends&number=91XXXXXXXXXX&
fullname=John&email=abc@gmail.com&format=xml

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method groups.register
API/Working key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
mobile number number mobile number of the contact(With or without 91) 99XXXXXXXX or 9199XXXXXXXX
group name name group name case insensitive

Optional Parameters

The optional parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
contact name fullname name of the contact name of the contact
email address email email of the contact email of the contact
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON
add/delete action action. Add is Default Flag to specify the action add/delete

Example Responses

<api>
  <status>OK</status>
  <message>Number has been added Successfully</message>
</api>
{
    "status": "OK",
    "message": "Number has been added Successfully",
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [message] => Campaign Submitted successfully 
)
{
    "status":"ERROR",
    "message":"Group Name does not exist!"
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the API to create a contact group is in the below format :

Status Message
A420 Group name/id missing
A421 Group is empty/Invalid group
A422 Invalid mobile number
A423 Group name/number missing
A424 Group Name does not exist!
A425 Number does not Exist

Sending Message to a group

The URL for sending a simple message to a group is in the following format:

http://URL/api/v3/index.php?method=groups&api_key=Ad9e5XXXXXXXXXXXXX&name=MYGROUP&sender=INFXXX&message=testing

The URL for sending a customized message to a group is in the following format:

http://URL/api/v3/index.php?method=groups&api_key=Ad9e5XXXXXXXXXXXXX&name=MYGROUP&sender=INFXXX&message=Dear {name}, Your email is {email}

Here {name} and {email} are variables and picked up from the group MYGROUP corresponding to each mobile number.

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method groups
API/Working key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
Sender ID sender Sender ID assigned to your account Sender ID
group name name Group name group name
Group ID id Group ID Comma seperated group ID
Message message Message to be sent Message text which is URL encoded(1000 char for normal, 500 for unicode)

Optional Parameters

The optional parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
Schedule time time Date and time for scheduling an SMS EX Format: YYYY-MM-DD HH:MM:SS OR YYYY-MM-DD HH:MM AM/PM
unicode unicode To specify that the message to be sent is in unicode format. Also can be used for automatic detection of unicode SMS. 1 / 0 / auto
flash flash To specify that the message is to be sent in the flash format 1 or 0

Advanced Parameters(Optional)

The advanced parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON
Callback function name callback Callback function for JSONP response format String

Example Responses

<api>
  <status>OK</status>
  <data>
    <group_id>2758</group_id>
    <groups>
      <id>2758-1</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
    </groups>
    <groups>
      <id>2758-2</id>
      <customid>1</customid>
      </customid1>
      </customid2>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
    </groups>
      ...
  </data>
  <message>Campaign of 2 numbers Submitted successfully.</message>
</api>
{
    "status": "OK",
    "data": 
    {
        "group_id":2758,
        "0":
        {
            "id": "2758-1",
            "customid": "1",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
        },
        "1":
        {
            "id": "2758-2",
            "customid": "2",
            "customid1": "",
            "customid2": "",
            "mobile": "9190********",
            "status": "AWAITED-DLR",
        }
            ...
    }
    "message": "Campaign Submitted successfully"
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [data] => Array
        (
            [group_id] => 2758
            [0] => Array
                (
                    [id] => 2758-6
                    [customid] => 1
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
  )
            [1] => Array
                (
                    [id] => 2758-7
                    [customid] => 2
                    [customid1] => 
                    [customid2] => 
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
  				)                    
             ...
        )
    [message] => Campaign Submitted successfully
)
{
    "status":"A404",
    "message":"Your api account got suspended"
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.
group_id Website group id for your reference
data All the response is wrapped in side data
groups Each number will be wrapped inside groups
id Website message id for your reference
customid Custom message id if you provide one
customid1 Custom message id 1 if you provide one
customid2 Custom message id 2 if you provide one
mobile Mobile number the sms will be sent
status status of the message

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the API to send message to a contact group is in the below format :

Status Message
A420 Group name/id missing
A421 Group is empty/Invalid group
A422 Invalid mobile number
A423 Group name/number missing
A424 Group Name does not exist!
A425 Number does not Exist

Delete Schedule

The URL for deleting an SMS slot that is scheduled is in the following format:

In order to delete a scheduled slot,there should a minimum gap of 15mins before its execution

http://URL/api/v3/index.php?method=sms.schedule&api_key=Ad9e5XXXXXXXXXXXXX&groupid=121&format=xml

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method sms.schedule
API/workingng key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
group ID groupid group id that has to be deleted group id that has to be deleted

Optional Parameters

The optional parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON

Example Responses

<api>
  <status>OK</status>
  <message>
    Campaign cancelled successfully and credits are refunded.
  </message>  
</api>
{
    "status": "OK",
    "message": "Campaign cancelled successfully and credits are refunded."
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [message] => Campaign cancelled successfully and credits are refunded.
)
{
    "status":"A432",
    "message":"Campaign already cancelled"
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the API to delete an SMS schedule is in the below format:

Status Message
A431 Invalid Group ID
A434 Campaign within next 15 minutes cannot be modified/canceled.

Edit Schedule

The URL for editing an SMS slot that is scheduled is in the following format:

In order to edit a scheduled slot,there should a minimum gap of 15mins before its execution

http://URL/api/v3/index.php?method=sms.schedule&api_key=Ad9e5XXXXXXXXXXXXX&groupid=121&format=xml&task=modify&time=24 dec 2014 9:00pm

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method sms.schedule
API/workingng key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
group ID groupid group id that has to be deleted group id that has to be deleted
task task Specifies that the scheduled time should be modified to the one mentioned within time parameter modify
time time Time to which the slot needs to be re-scheuled EX Format: YYYY-MM-DD HH:MM:SS OR YYYY-MM-DD HH:MM AM/PM

Optional Parameters

The optional parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON

Example Responses

<api>
  <status>OK</status>
  <message>
    Campaign updated successfully
  </message>  
</api>
{
    "status": "OK",
    "message": "Campaign updated successfully"
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [message] => Campaign updated successfully.
)
{
    "status":"A431",
    "message":"Invalid Group ID"
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the API to Edit an SMS schedule is in the below format :

STATUS MESSAGE
A431 Invalid Group ID
A434 Campaign within next 15 minutes cannot be modified/canceled.

Credits Availability Check

The URL for checking the credits in your account is in the following format:

http://URL/api/v3/index.php?method=account.credits&api_key=Ad9e5XXXXXXXXXXXXX

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method account.credits
API/workingng key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel

Optional Parameters

The optional parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON

Example Responses

<api>
  <status>OK</status>
  </message>
  <data>
    <credits>2758</credits>
  </data>
</api>
{
    "status": "OK",
    "message": "",
    "data": 
    {
      "credits": "2758"
    }
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [message] => 
    [data] => Array
        (
            [credits] => 2758
        )
)
{
    "status":"A404",
    "message":"Your api account got suspended"
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.
data All the response is wrapped in side data
credits Displays the credits available in the account

Checking SMS Status - PULL

The URL for checking the status of an SMS is in the following format:

http://URL/api/v3/index.php?method=sms.status&api_key=Ad9e5XXXXXXXXXXXXX&format=json&id=2191-1& numberinfo = 1

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method sms.status
API/Working key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
message id id Message ID, comma separated message id of messages sent in the last 3 days

Optional Parameters

The optional parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON
service provider and location flag numberinfo Flag to query service provider and location data 1 or 0

Example Responses

<api>
  <status>OK</status>
  <message>Processed Successfully</message>
  <data>
    <sms>
      <id>165-1</id>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
      <senttime>2014-09-01 04:05:06</senttime>
      <dlrtime>2014-09-01 04:05:18</dlrtime>
      </custom>   
      </custom1>
      </custom2>
      <provider>BSNL</provider>
      <location>JAMMU AND KASHMIR</location>
    </sms>
  </data>
</api>
{
    "status": "OK",
    "message": "Processed successfully",
    "data": 
            [{
                "id": "2758-1",
                "mobile": "9190********",
                "status": "AWAITED-DLR",
                "senttime":"2014-09-01 04:05:06",
                "dlrtime":"2014-09-01 04:05:18",
                "custom":"",
                "custom1": "",
                "custom2": "",
                "provider": "BSNL",
                "location": "JAMMU AND KASHMIR"
            }]
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [message] => Processed Successfully
    [data] => Array
        (
            [0] => Array
                (
                    [id] => 2758-6
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
                    [senttime] => 2014-09-01 04:05:06
                    [dlrtime] => 2014-09-01 04:05:18
                    [custom] => 
                    [custom1] => 
                    [custom2] => 
                    [provider] => BSNL
                    [location] => JAMMU AND KASHMIR
                
                )
        )
)
{
    "status":"A404",
    "message":"Your api account got suspended"
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.
data All the response is wrapped in side data
sms Each number will be wrapped inside sms
id Website message id for your reference
custom1 Custom message id 1 if you provide one
custom2 Custom message id 2 if you provide one
mobile Mobile number the sms will be sent
status status of the message
custom Custom message id if you provide one
senttime message sent time
dlrtime message delivered time
provider provider of the mobile numer
location Registered location of the mobile number

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the API to check sms status is in the below format:

STATUS MESSAGE
A417 Invalid Message ID/Mobile

Checking Group Status -PULL

The URL for checking group status is in the following format:

http://URL/api/v3/index.php?method=sms.groupstatus&api_key=Ad9e5XXXXXXXXXXXXX&format=json&groupid=2191& numberinfo = 1

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method sms.groupstatus
API/Working key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
group id groupid Custom group ID by customer, comma separated group id of campaign sent in the last 3 days

Optional Parameters

The optional parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
Response Type format Output format should be as specified by this variable XML/PHP/JSON/JSONP. Default response will be in JSON
service provider and location flag numberinfo Flag to query service provider and location data 1 or 0

Example Responses

<api>
  <status>OK</status>
  <message>Processed Successfully</message>
  <data>
    <sms>
      <id>165-1</id>
      <mobile>9190********</mobile>
      <status>AWAITED-DLR</status>
      <senttime>2014-09-01 04:05:06</senttime>
      <dlrtime>2014-09-01 04:05:18</dlrtime>
      </custom>   
      </custom1>
      </custom2>
      <provider>BSNL</provider>
      <location>JAMMU AND KASHMIR</location>
    </sms>
    <sms>
      <id>165-2</id>
      <mobile>9195********</mobile>
      <status>AWAITED-DLR</status>
      <senttime>2014-09-01 04:05:06</senttime>
      <dlrtime>2014-09-01 04:05:18</dlrtime>
      </custom>   
      </custom1>
      </custom2>
      <provider>BSNL</provider>
      <location>BANGALORE</location>
    </sms>
  </data>
</api>
{
    "status": "OK",
    "message": "Processed successfully",
    "data": 
            [{
                "id": "2758-1",
                "mobile": "9190********",
                "status": "AWAITED-DLR",
                "senttime":"2014-09-01 04:05:06",
                "dlrtime":"2014-09-01 04:05:18",
                "custom":"",
                "custom1": "",
                "custom2": "",
                "provider": "BSNL",
                "location": "JAMMU AND KASHMIR"
            },
            {
                 "id":"2758-2",
                 "mobile":"99XXXXXXXX",
                 "status":"UNDELIV",
                 "senttime":"2014-09-01 04:05:06",
                 "dlrtime":"2014-09-01 04:05:18",
                 "custom":"",
                 "custom1":NULL,
                 "custom2":NULL,
                 "provider":"BSNL",
                 "location":"BANGALORE"     
            }]
}
NOTE : Output Obtained After print_r(unserialize($response))
Array
(
    [status] => OK
    [message] => Processed Successfully
    [data] => Array
        (
            [0] => Array
                (
                    [id] => 2758-6
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
                    [senttime] => 2014-09-01 04:05:06
                    [dlrtime] => 2014-09-01 04:05:18
                    [custom] => 
                    [custom1] => 
                    [custom2] => 
                    [provider] => BSNL
                    [location] => JAMMU AND KASHMIR
                
                )
            [1] => Array
                (
                    [id] => 2758-7
                    [mobile] => 9190********
                    [status] => AWAITED-DLR
                    [senttime] => 2014-09-01 04:05:06
                    [dlrtime] => 2014-09-01 04:05:18
                    [custom] => 
                    [custom1] => 
                    [custom2] => 
                    [provider] => BSNL
                    [location] => JAMMU AND KASHMIR
                
                )
        )
)
{
    "status":"A404",
    "message":"Your api account got suspended"
}

Response Data

status It indicates the success or failure of your request.
message It indicates the success or failure message.
data All the response is wrapped in side data
sms Each number will be wrapped inside sms
id Website message id for your reference
custom1 Custom message id 1 if you provide one
custom2 Custom message id 2 if you provide one
mobile Mobile number the sms will be sent
status status of the message
custom Custom message id if you provide one
senttime message sent time
dlrtime message delivered time
provider provider of the mobile numer
location Registered location of the mobile number

API Error Codes

When certain parameters of the API URL are not entered correctly, you will receive a response from the URL stating the type of error. These error descriptions will help you to pin-point the erroneous parameter in the URL and rectify it.

The common error codes received while using the API to check group status is in the below format:

STATUS MESSAGE
A419 Invalid Group ID/Campaign

Checking SMS Status - PUSH

The URL for pushing the status of an SMS is in the following format:

http://{$domain}/v3/index.php?method=sms&api_key=Ad9e5XXXXXXXXXXXXX&to=997XXXXXXX&sender=INFXXX&message=testing&
format=json&custom=1&custom1=11&custom2=22&dlrurl=DLRURL

API Parameter Specifications

The API parameter specifications are described in the following sections.

Mandatory Parameters

The mandatory parameters in the HTTP API are tabulated below:

Name Parameter Description Expected Values
URL URL URL of your SMS Service URL
Method method Predefined method sms
API/Working key api_key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
Sender ID sender Sender ID assigned to your account Sender ID
Mobile number to Mobile number to which the SMS is to be sent.The destination mobile number can be with or without 91. Also provide multiple numbers in comma separated format. Mobile number(GET-10numbers,POST-100numbers)
Message message Message to be sent Message text which is URL encoded(1000 char for normal, 500 for unicode)
message id custom message id provided for Sms message id provided for Sms
delivery reports URL dlrurl The URL to receive delivery reports. Spiffing custom is mandatory. delivery reports URL

Example DLR URL

Value within the dlrurl should always be url encoded

http://test.net/dlr/trigger.php?sent={sent}&delivered={delivered}&custom={custom}&sid={sid}&status={status}&reference={reference}&custom1={custom1}&custom2={custom2}

Response as seen in DLR URL

2015-07-13 13:50:58 54.254.218.30
{"sent":"2015-07-13 19:20:46","delivered":"2015-07-13 19:20:57","custom":"1","sid":"1406368098-1","status":"DELIVRD","reference":"1","custom1":"11","custom2":"22","msgid":"1"}

Custom Flags in DLR URL

We have few custom flags supported in DLR URL in order to get the additional values. In case one wants to build the URL in above format, the following flags can be used.

Field Name Description
{custom} (alias-{reference}/{msgid}) Message ID provided by user
{sid} Message ID of the SMS generated by us
{sent} Sent time in YYYY-MM-DD HH:MM:SS format
{delivered} Delivered time in YYYY-MM-DD HH:MM:SS format
{status} SMS status code
{custom1} Custom Flag 1 associated with the message provided by the user
{custom2} Custom Flag 2 associated with the message provided by the user