API Reference

Loved by developers. Built for business.
TheSMSBuddy helps growing startups and agile enterprises enhance their customer experience and realize new business outcomes at scale. With our easy-to-use APIs, global platform, and expert support, you can abstract the complexity of communications and innovate faster.
Build it your way, and keep your developers happy. Your developers will get our ready-to-use, high-quality insights API, plus super-speedy support and a rockstar community network.
Introduction

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

Base URL for API Integration

Base URL will be defined as the common API URL parameters to be specified in every API trigger. All APIs shall contain this base URL.

https://thesmsbuddy.com/api/v1/
Check Account Balance

You can get the account balance of each service using this api.

https://thesmsbuddy.com/api/sms/balance/check

The following are the API Parameters

Parameter Description Expected Values
key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
Example Request
curl -X POST "https://thesmsbuddy.com/api/sms/balance/check" \
	-d "key=XXXXXXXXXXXXXXXXXXXXXXXX" 
Sample response
{
    "status": "200",
    "data": {
        "trans": 100,
        "promo": 0,
        "transscrub": 50
    }
}
Send SMS

The SMS API supports the following:

Note: As new DLT restrictions effective from Jan 31, we are suggesting to use the Template API for avoiding delivery issues related to DLT

POST - When you send a POST request with the end user’s phone number to the messaging subresource, We sends the SMS message you specify.

GET - You can retrieve the results of the message you sent using the GET method. You do this by sending a GET request containing the reference id for the message you sent.

We return a response message in the form of a JSON object in the entity body.

https://thesmsbuddy.com/api/v1/sms/send

Before you start sending transactional SMS through this API, please test whether your content is matching a template which has been pre approved. Otherwise, the SMS will end up being rejected.

The following are the API Parameters

Parameter Description Expected Values
key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
type Determines whether the SMS to be sent is Transactional, Promotional or other. 1: Transactional
2: Promotional
3: Transscrub
sender The registered and approved Sender-id Required
to Phone number to send with country prefix. (multiple numbers can be separated by comma.)
message The content of the SMS
template_id TemplateId registered in DLT portal (applicable for indian routes only)
schedule Set whether message needs to schedule 0: Normal message
1: Schedule message
time Schedule time at which the SMS has to be sent. time in format i.e,yyyy-mm-dd hh:mm:ssxx`
flash This parameter can be used to send flash sms via API (Optional) 0: Disable
1: Enable
dlr_url The URL you want to receive the status of the message. This URL can be accessed publicly. (Optional)
custom The custom parameter you wants to receive on callback (Optional)
Example Request
curl -X POST "https://thesmsbuddy.com/api/sms/send" \
	-d "key=XXXXXXXXXXXXXXXXXXXXXXXX" \
	-d "type=1" \
	-d "to=98xxxxxxxx" \
	-d "sender=SMSBDY" \
	-d "message=test message" \
	-d "template_id=1234567890123456789" 
Sample response
{
  "status": "200",
  "charges": 1,
  "message": "1 numbers accepted for delivery.",
  "data": [
    {
      "id": "4lso1rySHGz6cWfXVmwhD5hs-1",
      "mobile": "9198xxxxxxxx",
      "status": "AWAITING-DLR",
      "unit": 1,
      "length": 12,
      "charge": 1
    }
  ]
}
Send JSON SMS

You can send sms using POST method content in body.

All params in send sms will support in JSON also.

https://thesmsbuddy.com/api/v1/sms/send/json

root entry holds the default values for each node. You can overwite the root message values inside nodes value

Example Body
{
   "root":{
      "type":"1",
      "flash":"0",
      "sender":"XXXXXX",
      "message":"common test message",
      "key":"XHXdxxxxxxxxxxxxxxxxUci",
      "template_id":"XHXdxxxxxxxxxxxxxxxxUci",
   },
   "nodes":[
      {
         "to":"98xxxxxxxx",
         "message":"test message 1",
         "refid":"2"
      },
      {
         "to":"98xxxxxxxx"
      }
   ]
}

The following are the root parameters

Parameter Description Expected Values
key API/Working key generated from your SMS Account Alphanumeric working key generated from web panel
type Determines whether the SMS to be sent is Transactional, Promotional or other. 1: Transactional
2: Promotional
3: Transscrub
sender The registered and approved Sender-id Required
message The content of the SMS
template_id TemplateId registered in DLT portal (applicable for indian routes only)
flash This parameter can be used to send flash sms via API (Optional) 0: Disable
1: Enable
dlr_url The URL you want to receive the status of the message. This URL can be accessed publicly. (Optional)

The following are the node parameters

Parameter Description Expected Values
to Recipient's MSISDN Required
message The content of the SMS Optional. Will override root message
refid Reference parameter Optional
Example Request
curl --request POST \
  --url https://thesmsbuddy.com/api/v1/sms/send/json \
  -H 'Content-Type: application/json' \
  --data '{
   "root":{
      "type":"1",
      "flash":"0",
      "sender":"XXXXXX",
      "message":"common test message",
      "key":"XHXdxxxxxxxxxxxxxxxxUci",
      "template_id":"XHXdxxxxxxxxxxxxxxxxUci",
   },
   "nodes":[
      {
         "to":"98xxxxxxxx",
         "message":"test message 1",
         "refid":"2"
      },
      {
         "to":"98xxxxxxxx"
      }
   ]
}'
Sample response
{
  "status": "200",
  "charges": 2,
  "message": "2 numbers accepted for delivery.",
  "data": [
    {
      "id": "sMsq7YOOrYqRMibQlX1zKJJd-1",
      "mobile": "9198xxxxxxxx",
      "status": "AWAITING-DLR",
      "unit": 1,
      "length": 14,
      "charge": 1,
      "refid": 2
    },
    {
      "id": "sMsq7YOOrYqRMibQlX1zKJJd-2",
      "mobile": "9198xxxxxxxx",
      "status": "AWAITING-DLR",
      "unit": 1,
      "length": 19,
      "charge": 1,
      "refid": ""
    }
  ]
}
Error Codes

You can get the account balance of each service using this api.

Error Code Description
200 Success Response
400 Incomplete request - Any one of mandatory field missing
422 Invalid Service Type
401 Invalid API Key
412 Invalid Sender ID
451 Sorry, this service is allowed only between 10AM & 9PM - Monday to Sunday. Request you to kindly try scheduling the campaign during the said timings. Thank you.
406 No Valid Numbers
416 Service Not Available
409 Insufficient Balance
429 Too many requests received. Your threshold value is 1000 SMS/minute. Please contact support.
500 There is an issue at our end. Please submit your request again.
We are happy to help you!

Please fill in the below details for us to get in touch with you.