Developer API Reference

Complete HTTP(s) API reference for Third Party Integrations

Rich set of REST Compatible APIs

SMS Handover offers amazing selection of APIs for messaging, credit check and delivery reports. Our API supports push-callback or the webhook method for instant DLR push. These APIs are high performance with support upto 50,000 message per request via HTTP POST. Create an account with us to explore full API offerings.



API ENDPOINT (GET and POST) Send SMS API

https://console.smshandover.com/smsapi/index

Parameters Meaning Description
key= API Key
(required)		 An API Key assigned to your account
&campaign= as defined in description
(optional) 		Campaigns are for organizing your messages. Enter ID of campaign as shown below. You can use 0 (zero) or skip it for the default campaign.
&routeid= ID of the route as defined in description
(optional) 		For account with multiple marketing channels (or Routes), supply route ID here. It will be displayed in API details within your portal.
&type= SMS Type
(optional)		 text, unicode, flash etc. Default is text
&contacts= Contact Numbers
(required)		 Contact numbers separated by ‘ , ‘ (comma) sign
e.g. 919887XXXXXX,919567XXXXXX
For accurate routing, supply mobile numbers including the country prefix.
&senderid= Sender ID
(required)		 Any Approved Sender ID from your account
&msg= SMS Text
(required)		 Url-encoded SMS text. Must be limited to 720 characters
&time= Schedule Time
(optional)		 Enter the time in the format YYYY-MM-DD H:I e.g. enter 2013-03-19 14:30 for 19th March 2013, 2:30 pm. Leave BLANK to send the SMS instantly.
&bulk_campaigm= Optional for multiple submission
(optional) 		For personalized campaign supply the values like shown below:.
                                      
[{
    "mobile":9887xxxxxx,
    "msg":"hiPeter"
  },
  {
    "mobile":8009xxxxxx,
  "msg":"hiJohn"
}]
&dlr_url= Optional URL to post DLR
(optional) 		You can provide a URL where our system will post delivery reports.

Responses

API Response Description 

{
"result": "error",
"message": "INVALID API KEY"
}
An error occurred while submitting the API call request. The source of error would be explained in the braces {}, for instance, “ERR: INVALID API KEY” means the API key entered is expired or does not belong to any user. The error messages are not ciphered and pretty much intuitive. 
                                      
{ 
  "result": "success", 
  "message": "SMS SUBMITTED SUCCESSFULLY", 
  "sms_shoot_id":"kJ09981hjkksuj95" 
}
This means SMS was submitted successfully, and it returns the shoot-id of the submission. You could use this ID to pull out delivery reports.
Sample URL & Sample API Codes
Simple SMS 

                                        
$api_url =
"https://console.smshandover.com/smsapi/index?key=A277GF664N88EMD993D9400F04EDIC&campaign=0&type=text&contacts=9197656XXXXX,9198012XXXXX&senderid=DEMO&msg=Hello+People%2C+have+a+great+day";
Scheduled SMS 

                                        
																				$api_url =
																				"https://console.smshandover.com/smsapi/index?key=A277GF664N88EMD993D9400F04EDIC&campaign=1&type=text&contacts=9197656XXXXX,9198012XXXXX&senderid=DEMO&msg=Hello+People%2C+have+a+great+day&time=2023-08-03+09%3A43";
Sample Codes 
                    
<?php
$url = 'https://console.smshandover.com/smsapi/index?key=A277GF664N88EMD993D9400F04EDIC&campaign=0&type=text&contacts=9197656XXXXX,9198012XXXXX&senderid=DEMO&msg=Hello+People%2C+have+a+great+day';
$response = file_get_contents($url);

if ($response !== false) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo 'Failed to retrieve data from the API.';
}
?>
                    
                
                    
const fetch = require('node-fetch');

fetch('https://console.smshandover.com/smsapi/index?key=A277GF664N88EMD993D9400F04EDIC&campaign=0&type=text&contacts=9197656XXXXX,9198012XXXXX&senderid=DEMO&msg=Hello+People%2C+have+a+great+day')
    .then(response => response.json())
    .then(data => {
        console.log(data);
    })
    .catch(error => {
        console.error('Failed to retrieve data from the API.');
    });
                    
                
                    
package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    url := "https://console.smshandover.com/smsapi/index?key=A277GF664N88EMD993D9400F04EDIC&campaign=0&type=text&contacts=9197656XXXXX,9198012XXXXX&senderid=DEMO&msg=Hello+People%2C+have+a+great+day"
    response, err := http.Get(url)
    if err != nil {
        fmt.Println("Failed to retrieve data from the API.")
        return
    }
    defer response.Body.Close()

    body, err := ioutil.ReadAll(response.Body)
    if err != nil {
        fmt.Println("Failed to read response body.")
        return
    }

    fmt.Println(string(body))
}
                    
                
                    
import requests

url = 'https://console.smshandover.com/smsapi/index?key=A277GF664N88EMD993D9400F04EDIC&campaign=0&type=text&contacts=9197656XXXXX,9198012XXXXX&senderid=DEMO&msg=Hello+People%2C+have+a+great+day'
response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print('Failed to retrieve data from the API.')
                    
                
                    
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string url = "https://console.smshandover.com/smsapi/index?key=A277GF664N88EMD993D9400F04EDIC&campaign=0&type=text&contacts=9197656XXXXX,9198012XXXXX&senderid=DEMO&msg=Hello+People%2C+have+a+great+day";

        using (HttpClient client = new HttpClient())
        {
            try
            {
                HttpResponseMessage response = await client.GetAsync(url);
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
            catch (HttpRequestException)
            {
                Console.WriteLine("Failed to retrieve data from the API.");
            }
        }
    }
}
                    
                
                    
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        String url = "https://console.smshandover.com/smsapi/index?key=A277GF664N88EMD993D9400F04EDIC&campaign=0&type=text&contacts=9197656XXXXX,9198012XXXXX&senderid=DEMO&msg=Hello+People%2C+have+a+great+day";
        
        try {
            URL apiURL = new URL(url);
            HttpURLConnection connection = (HttpURLConnection) apiURL.openConnection();
            connection.setRequestMethod("GET");
            
            int responseCode = connection.getResponseCode();
            if (responseCode == 200) {
                Scanner scanner = new Scanner(connection.getInputStream());
                while (scanner.hasNextLine()) {
                    System.out.println(scanner.nextLine());
                }
                scanner.close();
            } else {
                System.out.println("Failed to retrieve data from the API.");
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}


API ENDPOINT (GET) BALANCE CHECK API

https://console.smshandover.com/miscapi/< api-key >/getBalance/true/

Parameters Meaning Description
api-key API Key
(required)		 An API Key assigned to your account

Responses

API Response Description 
                                      
ERR: {<MESSAGE>}
An error occurred while submitting the API call request. The source of error would be explained in the braces {}, for instance, “ERR: INVALID API KEY” means the API key entered is expired or does not belong to any user. The error messages are not ciphered and pretty much intuitive. 
                                      
[{
"ROUTE_ID":"<id>",
"ROUTE":"<name of the route>",
"BALANCE":"<credit balance>"
}]
This will return a JSON Array with specified values
Sample URL & Sample API Codes
Simple Call 
                                        
$api_url = "https://console.smshandover.com/miscapi/A277GF664N88EMD993D9400F04EDIC/getBalance/true/";
Sample Codes 
                    
<?php
$url = 'https://console.smshandover.com/miscapi/A277GF664N88EMD993D9400F04EDIC/getBalance/true/';
$response = file_get_contents($url);

if ($response !== false) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo 'Failed to retrieve data from the API.';
}
?>
                    
                
                    
const fetch = require('node-fetch');

fetch('https://console.smshandover.com/miscapi/A277GF664N88EMD993D9400F04EDIC/getBalance/true/')
    .then(response => response.json())
    .then(data => {
        console.log(data);
    })
    .catch(error => {
        console.error('Failed to retrieve data from the API.');
    });
                    
                
                    
package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    url := "https://console.smshandover.com/miscapi/A277GF664N88EMD993D9400F04EDIC/getBalance/true/"
    response, err := http.Get(url)
    if err != nil {
        fmt.Println("Failed to retrieve data from the API.")
        return
    }
    defer response.Body.Close()

    body, err := ioutil.ReadAll(response.Body)
    if err != nil {
        fmt.Println("Failed to read response body.")
        return
    }

    fmt.Println(string(body))
}
                    
                
                    
import requests

url = 'https://console.smshandover.com/miscapi/A277GF664N88EMD993D9400F04EDIC/getBalance/true/'
response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print('Failed to retrieve data from the API.')
                    
                
                    
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string url = "https://console.smshandover.com/miscapi/A277GF664N88EMD993D9400F04EDIC/getBalance/true/";

        using (HttpClient client = new HttpClient())
        {
            try
            {
                HttpResponseMessage response = await client.GetAsync(url);
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
            catch (HttpRequestException)
            {
                Console.WriteLine("Failed to retrieve data from the API.");
            }
        }
    }
}
                    
                
                    
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        String url = "https://console.smshandover.com/miscapi/A277GF664N88EMD993D9400F04EDIC/getBalance/true/";
        
        try {
            URL apiURL = new URL(url);
            HttpURLConnection connection = (HttpURLConnection) apiURL.openConnection();
            connection.setRequestMethod("GET");
            
            int responseCode = connection.getResponseCode();
            if (responseCode == 200) {
                Scanner scanner = new Scanner(connection.getInputStream());
                while (scanner.hasNextLine()) {
                    System.out.println(scanner.nextLine());
                }
                scanner.close();
            } else {
                System.out.println("Failed to retrieve data from the API.");
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}
dlr


API ENDPOINT (GET and POST) Send OTP API

https://console.smshandover.com/send-otp/index

Parameters Meaning Description
key= API Key
(required)		 An API Key assigned to your account
channel_id= as defined in description Mandatory. Enter the channel ID to be used for OTP.
mobile= phone number to verify mobile number with country code
e.g. 919887XXXXXX

Responses

API Response Description 
                                      
{
"result": "success",
"reference": "KSJ734NDJX88E9MDI"
}
API call was successful and a reference will be provided. Use this in next API call to verify OTP 
                                      
{
"result": "error",
"message": "MISSING CHANNEL ID"
}
An error occurred while submitting the API call request. The source of error would be explained in the braces {}, for instance, "ERR: MISSING CHANNEL ID" means tere was no channel ID supplied. The error messages are not ciphered and pretty much intuitive.
Sample URL & Sample API Codes
Simple Call 
                                        
$api_url = "https://console.smshandover.com/send-otp/index?key=A277GF664N88EMD993D9400F04EDIC&channel_id=x&mobile=9198871XXXXX";
Sample Codes 
                    
<?php
$url = 'https://console.smshandover.com/send-otp/index?key=A277GF664N88EMD993D9400F04EDIC&channel_id=x&mobile=9198871XXXXX';
$response = file_get_contents($url);

if ($response !== false) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo 'Failed to retrieve data from the API.';
}
?>
                    
                
                    
const fetch = require('node-fetch');

fetch('https://console.smshandover.com/send-otp/index?key=A277GF664N88EMD993D9400F04EDIC&channel_id=x&mobile=9198871XXXXX')
    .then(response => response.json())
    .then(data => {
        console.log(data);
    })
    .catch(error => {
        console.error('Failed to retrieve data from the API.');
    });
                    
                
                    
package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    url := "https://console.smshandover.com/send-otp/index?key=A277GF664N88EMD993D9400F04EDIC&channel_id=x&mobile=9198871XXXXX"
    response, err := http.Get(url)
    if err != nil {
        fmt.Println("Failed to retrieve data from the API.")
        return
    }
    defer response.Body.Close()

    body, err := ioutil.ReadAll(response.Body)
    if err != nil {
        fmt.Println("Failed to read response body.")
        return
    }

    fmt.Println(string(body))
}
                    
                
                    
import requests

url = 'https://console.smshandover.com/send-otp/index?key=A277GF664N88EMD993D9400F04EDIC&channel_id=x&mobile=9198871XXXXX'
response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print('Failed to retrieve data from the API.')
                    
                
                    
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string url = "https://console.smshandover.com/send-otp/index?key=A277GF664N88EMD993D9400F04EDIC&channel_id=x&mobile=9198871XXXXX";

        using (HttpClient client = new HttpClient())
        {
            try
            {
                HttpResponseMessage response = await client.GetAsync(url);
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
            catch (HttpRequestException)
            {
                Console.WriteLine("Failed to retrieve data from the API.");
            }
        }
    }
}
                    
                
                    
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        String url = "https://console.smshandover.com/send-otp/index?key=A277GF664N88EMD993D9400F04EDIC&channel_id=x&mobile=9198871XXXXX";
        
        try {
            URL apiURL = new URL(url);
            HttpURLConnection connection = (HttpURLConnection) apiURL.openConnection();
            connection.setRequestMethod("GET");
            
            int responseCode = connection.getResponseCode();
            if (responseCode == 200) {
                Scanner scanner = new Scanner(connection.getInputStream());
                while (scanner.hasNextLine()) {
                    System.out.println(scanner.nextLine());
                }
                scanner.close();
            } else {
                System.out.println("Failed to retrieve data from the API.");
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}


API ENDPOINT (GET and POST) Verify OTP API

https://console.smshandover.com/verify-otp/index

Parameters Meaning Description
key= API Key
(required)		 An API Key assigned to your account
reference= as defined in description Mandatory. Supply the reference received during Send OTP API call.
otp= one-time password to match supply the OTP entered by user here

Responses

API Response Description 
                                      
{
"result": "success",
"match": "true"
}
API call was successful and OTP was matched 
                                      
{
"result": "success",
"match": "false"
}
API call was successful BUT OTP entered was wrong. 
                                      
{
"result": "success",
"match": "expired"
}
API call was successful BUT OTP is expired or too many attempts 
                                      
{
"result": "error",
"message": "MISSING REFERENCE"
}
An error occurred while submitting the API call request. The source of error would be explained in the braces {}, for instance, "ERR: MISSING REFERENCE" means tere was supplied reference was empty. The error messages are not ciphered and pretty much intuitive.
Sample URL & Sample API Codes
Simple Call 
                                        
$api_url = "https://console.smshandover.com/verify-otp/index?key=A277GF664N88EMD993D9400F04EDIC&reference=DJJD730ND930C993&otp=909812";
Sample Codes 
                    
<?php
$url = 'https://console.smshandover.com/verify-otp/index?key=A277GF664N88EMD993D9400F04EDIC&reference=DJJD730ND930C993&otp=909812';
$response = file_get_contents($url);

if ($response !== false) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo 'Failed to retrieve data from the API.';
}
?>
                    
                
                    
const fetch = require('node-fetch');

fetch('https://console.smshandover.com/verify-otp/index?key=A277GF664N88EMD993D9400F04EDIC&reference=DJJD730ND930C993&otp=909812)
    .then(response => response.json())
    .then(data => {
        console.log(data);
    })
    .catch(error => {
        console.error('Failed to retrieve data from the API.');
    });
                    
                
                    
package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
)

func main() {
    url := "https://console.smshandover.com/send-otp/index?key=A277GF664N88EMD993D9400F04EDIC&channel_id=x&mobile=9198871XXXXX"
    response, err := http.Get(url)
    if err != nil {
        fmt.Println("Failed to retrieve data from the API.")
        return
    }
    defer response.Body.Close()

    body, err := ioutil.ReadAll(response.Body)
    if err != nil {
        fmt.Println("Failed to read response body.")
        return
    }

    fmt.Println(string(body))
}
                    
                
                    
import requests

url = 'https://console.smshandover.com/verify-otp/index?key=A277GF664N88EMD993D9400F04EDIC&reference=DJJD730ND930C993&otp=909812'
response = requests.get(url)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print('Failed to retrieve data from the API.')
                    
                
                    
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string url = "https://console.smshandover.com/verify-otp/index?key=A277GF664N88EMD993D9400F04EDIC&reference=DJJD730ND930C993&otp=909812";

        using (HttpClient client = new HttpClient())
        {
            try
            {
                HttpResponseMessage response = await client.GetAsync(url);
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
            catch (HttpRequestException)
            {
                Console.WriteLine("Failed to retrieve data from the API.");
            }
        }
    }
}
                    
                
                    
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        String url = "https://console.smshandover.com/verify-otp/index?key=A277GF664N88EMD993D9400F04EDIC&reference=DJJD730ND930C993&otp=909812";
        
        try {
            URL apiURL = new URL(url);
            HttpURLConnection connection = (HttpURLConnection) apiURL.openConnection();
            connection.setRequestMethod("GET");
            
            int responseCode = connection.getResponseCode();
            if (responseCode == 200) {
                Scanner scanner = new Scanner(connection.getInputStream());
                while (scanner.hasNextLine()) {
                    System.out.println(scanner.nextLine());
                }
                scanner.close();
            } else {
                System.out.println("Failed to retrieve data from the API.");
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}