Introduction

Welcome to the NGH SMS API! You can use our API to send SMS, receive DLRs and fetch your account balance.

We have language bindings in Shell, C#, Python, JavaScript, PhP and Java! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

To test the SMS API, you will need a valid API account. If you don't have one yet, click here to register for a FREE account.

Authentication

To authorize, use this payload alongside other JSON params:




  {
    "api_key": k_RdFidnulkkY7UVfmNtPZgL9C11J,
    "api_secret": s_rtRdFkkllfmNtPZgL9C11J,
   }

Make sure to replace with your actual API key and secret.

NGH SMS API uses API key and API secret to allow access to the API. You can register a new API key and secret at our developer portal.

The API expects the API key and secret to be included in all API requests as part of the parameters supplied as follows:

api_Key: k_RdFidnulkkY7UVfmNtPZgL9C11J

api_secret: s_gTWNjzxXUKddffO8aio1vXC_jLOIiJ

You must replace the above api key and secret with your personal API key and secret from your account.

SMS

Send Single SMS

 
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://extranet.nghcorp.net/api/send-sms',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{ 
    "from": "senderid",
    "to": 22892470847,
    "text": "text sms",
    "reference": 1212,
    "api_key": "api_key",
    "api_secret": "api_secret"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

 
import http.client
import json

conn = http.client.HTTPSConnection("extranet.nghcorp.net")
payload = json.dumps({
    "from": "senderid",
    "to": 22892470847,
    "text": "text sms",
    "reference": 1212,
    "api_key": "api_key",
    "api_secret": "api_secret"
})
headers = {
  'Content-Type': 'application/json'
}
conn.request("POST", "/api/send-sms", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

 curl --location 'https://extranet.nghcorp.net/api/send-sms' \
--header 'Content-Type: application/json' \
--data '{ 
    "from": "senderid",
    "to": 22892470847,
    "text": "text sms",
    "reference": 1212,
    "api_key": "api_key",
    "api_secret": "api_secret"
}'

 
var data = JSON.stringify({
    "from": "senderid",
    "to": 22892470847,
    "text": "text sms",
    "reference": 1212,
    "api_key": "api_key",
    "api_secret": "api_secret"
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://extranet.nghcorp.net/api/send-sms");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);

 
var options = new RestClientOptions("https://extranet.nghcorp.net")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("/api/send-sms", Method.Post);
request.AddHeader("Content-Type", "application/json");
var body = @"{ " + "\n" +
@"    ""from"": ""senderid""," + "\n" +
@"    ""to"": 22892470847," + "\n" +
@"    ""text"": ""text sms""," + "\n" +
@"    ""reference"": 1212," + "\n" +
@"    ""api_key"": ""api_key""," + "\n" +
@"    ""api_secret"": ""api_secret""" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);

 
Unirest.setTimeouts(0, 0);
HttpResponse response = Unirest.post("https://extranet.nghcorp.net/api/send-sms")
  .header("Content-Type", "application/json")
  .body("{ \n    \"from\": \"senderid\",\n    \"to\": 22892470847,\n    \"text\": \"text sms\",\n    \"reference\": 1212,\n    \"api_key\": \"api_key\",\n    \"api_secret\": \"api_secret\"\n}")
  .asString();

The above command returns JSON structured like this:

{
  "status": 200,
  "status_desc": "Success",
  "messageid": "23344555",
  "credits": 501
   
}

This endpoint sends to a single number

HTTP Request

POST https://extranet.nghcorp.net/api/send-sms

Query Parameters

Parameter	Description	Type	Option
api_Key	Key provided	String	Mandatory
api_secret	Secret to be provided	String	Mandatory
to	Destination number	Numeric	Mandatory
from	Source address	String	Mandatory
text	Your message	String	Mandatory
reference	Unique identifier	String	Mandatory

Query Response (JSON Payload)

Parameter	Description	Type	Option
Status	200 - Success 400 - Failed	Numeric	Mandatory
status_desc	Status description	String	Mandatory
message_id	Reference on the server side	String	Optional
balance	Credits Balance	Numeric	Optional

Send Multiple SMS

 

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://extranet.nghcorp.net/api/send-multiple',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "credentials":{
           "api_key":"k_3uieonhsd",
           "api_secret":"s_kshdhjsd8hsd"
           },
    "messages":[
        {
            "from":"SENDER",
            "to":["2287945223342","2287945223341"],
            "content":"message 1"
            },
        {
            "from":"SENDER2",
            "to":228794521178,
            "content":"message 2"
            }
]
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;


import http.client
import json

conn = http.client.HTTPSConnection("extranet.nghcorp.net")
payload = json.dumps({
    "credentials":{
           "api_key":"k_3uieonhsd",
           "api_secret":"s_kshdhjsd8hsd"
           },
    "messages":[
        {
            "from":"SENDER",
            "to":["2287945223342","2287945223341"],
            "content":"message 1"
            },
        {
            "from":"SENDER2",
            "to":228794521178,
            "content":"message 2"
            }
]
})
headers = {
  'Content-Type': 'application/json'
}
conn.request("POST", "/api/send-multiple", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

 
curl --location 'https://extranet.nghcorp.net/api/send-multiple' \
--header 'Content-Type: application/json' \
--data '{
    "credentials":{
           "api_key":"k_3uieonhsd",
           "api_secret":"s_kshdhjsd8hsd"
           },
    "messages":[
        {
            "from":"SENDER",
            "to":["2287945223342","2287945223341"],
            "content":"message 1"
            },
        {
            "from":"SENDER2",
            "to":228794521178,
            "content":"message 2"
            }
]
}'

 
var data = JSON.stringify({
    "credentials":{
           "api_key":"k_3uieonhsd",
           "api_secret":"s_kshdhjsd8hsd"
           },
    "messages":[
        {
            "from":"SENDER",
            "to":["2287945223342","2287945223341"],
            "content":"message 1"
            },
        {
            "from":"SENDER2",
            "to":228794521178,
            "content":"message 2"
            }
]
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://extranet.nghcorp.net/api/send-multiple");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);

 
var options = new RestClientOptions("https://extranet.nghcorp.net")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("/api/send-multiple", Method.Post);
request.AddHeader("Content-Type", "application/json");
var body = @"{" + "\n" +
@"    ""credentials"":{" + "\n" +
@"           ""api_key"":""k_3uieonhsd""," + "\n" +
@"           ""api_secret"":""s_kshdhjsd8hsd""" + "\n" +
@"           }," + "\n" +
@"    ""messages"":[" + "\n" +
@"        {" + "\n" +
@"            ""from"":""SENDER""," + "\n" +
@"            ""to"":[""2287945223342"",""2287945223341""]," + "\n" +
@"            ""content"":""message 1""" + "\n" +
@"            }," + "\n" +
@"        {" + "\n" +
@"            ""from"":""SENDER2""," + "\n" +
@"            ""to"":228794521178," + "\n" +
@"            ""content"":""message 2""" + "\n" +
@"            }" + "\n" +
@"]" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);

 

Unirest.setTimeouts(0, 0);
HttpResponse response = Unirest.post("https://extranet.nghcorp.net/api/send-multiple")
  .header("Content-Type", "application/json")
  .body("{\n    \"credentials\":{\n           \"api_key\":\"k_3uieonhsd\",\n           \"api_secret\":\"s_kshdhjsd8hsd\"\n           },\n    \"messages\":[\n        {\n            \"from\":\"SENDER\",\n            \"to\":[\"2287945223342\",\"2287945223341\"],\n            \"content\":\"message 1\"\n            },\n        {\n            \"from\":\"SENDER2\",\n            \"to\":228794521178,\n            \"content\":\"message 2\"\n            }\n]\n}")
  .asString();

The above command returns JSON structured like this:

 [
  
{
    "status": 200,
    "description": "Submitted",
    "to": "2287945223342",
    "from": SENDER,
    "id": 1689574280,
    "cost": 1
  },

  "status": 200,
    "description": "Submitted",
    "to": "2287945223341",
    "from": SENDER,
    "id": 1689574281,
    "cost": 1,
  },
{
    "status": 405,
    "description": "Invalid param - from",
    "to": "228794521178",
    "from": SENDER2,
  }]

This endpoint sends multiple SMS at the same time.

HTTP Request

POST https://extranet.nghcorp.net/api/send-multiple

Post Parameters

Parameter	Description	Type	Option
credentials	api_key api_secret	JSON payload	All params mandatory
messages	from to content	JSON payload	All params mandatory

Query Response (JSON Payload)

Parameter	Description	Type	Option
Status	numeric status eg 200, 403	Numeric	Mandatory
status_desc	Status description	String	Mandatory
message_id	Reference on the server side	String	Optional
cost	SMS cost	Numeric	Optional
to	Destination mobile	String	Mandatory
from	Sender ID	String	Optional
text	Message sent	string	Optional

Receive Delivery Reports

 

https://clienturl.com/dlr/receive?mobile_number=228999999&message_id=1212&status=1

The below GET call to your URL to should return http status code 200

 
 Received

This section specifies how to receive delivery reports

HTTP Request

GET http://your-url.com/dlr/

URL Parameters

Parameter	Description	Type	Option
message_id	The unique identifier for the message which you received from our system	String	Mandatory
status	The actual status of the message. Refer to the table below	Numeric	Mandatory
mobile_number	The destination mobile number	String	Mandatory

Status Codes

Status	Meaning
1	Success
2	Failed
3	Blacklisted

Fetch Balance

 
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://extranet.nghcorp.net/api/balance',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "api_key": "api_key",
    "api_secret": "api_secret"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

 
import http.client
import json

conn = http.client.HTTPSConnection("extranet.nghcorp.net")
payload = json.dumps({
    "api_key": "api_key",
    "api_secret": "api_secret"
})
headers = {
  'Content-Type': 'application/json'
}
conn.request("POST", "/api/send-sms", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

 curl --location 'https://extranet.nghcorp.net/api/send-sms' \
--header 'Content-Type: application/json' \
--data '{ 
    "api_key": "api_key",
    "api_secret": "api_secret"
}'

 
var data = JSON.stringify({
    "api_key": "api_key",
    "api_secret": "api_secret"
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function() {
  if(this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://extranet.nghcorp.net/api/send-sms");
xhr.setRequestHeader("Content-Type", "application/json");

xhr.send(data);

 
var options = new RestClientOptions("https://extranet.nghcorp.net")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("/api/send-sms", Method.Post);
request.AddHeader("Content-Type", "application/json");
var body = @"{ " + "\n" +
@"    ""api_key"": ""api_key""," + "\n" +
@"    ""api_secret"": ""api_secret""" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);

 
Unirest.setTimeouts(0, 0);
HttpResponse response = Unirest.post("https://extranet.nghcorp.net/api/send-sms")
  .header("Content-Type", "application/json")
  .body("{ \"api_key\": \"api_key\",\n    \"api_secret\": \"api_secret\"\n}")
  .asString();

The above command returns JSON structured like this:

 {
  
"status": 200,
"status_desc": balance fetched successfully
"balance" : 455
}

This section specifies how to retrieve your account balance

HTTP Request

POST https://extranet.nghcorp.net/api/balance

Query Parameters

Parameter	Description	Type	Option
api_Key	Key provided	String	Mandatory
api_secret	Secret to be provided	String	Mandatory

Response Parameters

Parameter	Description	Type	Option
status	If the request was successful or not	String	Mandatory
status_desc	Status description	String	Mandatory
balance	Remaining Balance	Numeric	Mandatory

SMPP SMS

The API uses the following connection parameters:

Parameter	Meaning
host	URL or IP of the smpp server
port	the smpp port
username	System ID unique to your account
password	Authentication password

Errors

The API uses the following error codes:

Error Code	Meaning
100	Only POST is allowed.
101	Invalid JSON
102	Missing credentials
103	Invalid credentials
104	No data
105	Missing from parameter.
106	Sender ID error
107	Missing message.
108	Missing to number
109	Invalid to number
110	Route not found
111	Insufficient credit
112	Billing problem
113	Unable to send sms - internal error