API Reference

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

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

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

The following are the node parameters

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": ""
    }
  ]
}

Send OTP 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/otp/create

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

Example Request

curl -X POST "https://thesmsbuddy.com/api/otp/create" \
	-d "key=XXXXXXXXXXXXXXXXXXXXXXXX" \
	-d "to=98xxxxxxxx" \
	-d "sender=SMSBDY" \
	-d "message=Your Verification code is {#otp#}." \
	-d "template_id=1234567890123456789" 

Sample response

{
	"status":"200",
	"message":"OTP Generated Successfully",
	"otp":{
		"mobile":"9198xxxxxxxx",
		"status":"PENDING",
		"otp":"1234",
		"expiry":"2022-03-09 07:38:06"
	},
	"sms":{
		"id":"N8yB47bNaR5sfIlbnATKCZyE-1",
		"mobile":"9198xxxxxxxx",
		"status":"AWAITING-DLR",
		"unit":1,
		"length":33,
		"charge":1
	}
}

Verify OTP

https://thesmsbuddy.com/api/v1/otp/verify

The following are the API Parameters

Example Request

curl -X POST "https://thesmsbuddy.com/api/otp/verify" \
	-d "key=XXXXXXXXXXXXXXXXXXXXXXXX" \
	-d "to=98xxxxxxxx" \
	-d "otp=123456" 

Sample response

{
	"status":"200",
	"message":"OTP Verified Successfully"
}

Create Sender ID

The Sender ID creation API supports the following:

https://thesmsbuddy.com/api/v1/senderid/create

The following are the API Parameters

Example Request

curl -X POST "https://thesmsbuddy.com/api/senderid/create" \
	-d "key=XXXXXXXXXXXXXXXXXXXXXXXX" \
	-d "senderid=SMSBDY" \
	-d "description=my sender id description" \
	-d "pe_id=XXXXXXXXXX" \
	-d "header_id=XXXXXXXXXXX" 

Sample response

{
  "status": "200",
  "message": "Sender ID requested Successfully."
}

Error Codes

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