NAV
json php python ruby

Introduction

Welcome to the Nasara Mobile API! You can use our API to access Nasara Mobile’s API endpoints, which you can use to send SMS and interact with information on our database.

Our fast, simple, easy and robust Aplication Interface, API, allows programmers/developers to use our gateway in their applications to send sms.

We have language bindings in Shell, Ruby, and Python! 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.

Build Intelligent Applications

Nasara Mobile lets you use standard web languages to build SMS applications. We’re connected to carrier networks in Ghana (for now) and expose them to you via our clean, powerful and robust API. Check out our free sample codes for a fast and easy implementation of our API. Let’s start coding NOW!

Build Great and Fast Applications

Take your skills to the next level and build apps that make your look good and solve a problems, such as, Store Locators, Balance Lookup, Announcements, Reminders, Renewals & Upgrades Status Updates Product & Service Alerts, Mobile Coupons, etc.

API Versioning

The Nasara Mobile API currently has two versions; - Version 1 and - Version 2 (v2)

Version 1

The first version of the API was released in 2013 and has a very simple base url without the use of a version indicator

http://sms.nasaramobile.com/api?api_key=xxxxxxx&sender_id=yoursenderid&phone=xxxxxx&message

Version 1 only has two api calls (sending sms and checking account credit) and both request methods are GET. This version is currently still available for use and developers can choose which requests work best for them.

Version 2

Below is a typical JSON response in version 2 of the API

{
  "status": 200,
  "code": 1816,
  "data": null,
  "message": "Messages processed successfully!",
  "url": "http://sms.nasaramobile.com/api/v2/sendsms?api_key=567c1299197d5567c1299197e1&phone_numbers=233244209193&sender_id=NasaraMobleo&message=hello%20my%20friends!&groups=112,116&contacts=297367,297368,297369"
}

The second version of the API is a huge improvement from the first version. Version 2 is RESTFUL and provides more API calls with beautifully formatted JSON responses.

API calls have the version number in the base URI;

http://sms.nasaramobile.com/api/v2

API Libraries

Nasara Mobile has API libraries in PHP, Ruby and Python to help you easily integrate API into your project. We want to make sure you have a good experience with our API.

To get started using the client library, download or clone the repository from Github, include it in your application and checkout the examples or sample code implementation docs.

All examples in this documentation will assume you are using the library, where applicable. You can also make raw API calls if you wish without using the client libraries.

PHP Library

https://github.com/NasaraTech/Nasara-Mobile-PHP-API-Client

Ruby Library

https://github.com/NasaraTech/Nasara-Mobile-Ruby-API-Client

Python Library

https://github.com/NasaraTech/Nasara-Mobile-Python-API-Client

Authentication

An API Key is required for authenticating every request made via the API. To get an API Key, follow the steps below:

Send SMS

Version 1

    Response codes;

    1801 - message sent
    1802 - message sending failed
    1803 - invalid api key
    1804 - not enough credit
    1805 - invalid sender id
    1806 - phone number must be more than 8 characters
    1807 - message not posted
    <?php

        $url = "http://sms.nasaramobile.com/api?api_key=$api_key&&sender_id=$sender_id&&phone=$phone&&message=".urlencode($message)."";

        //send message and get response
        $response = file_get_contents($url);
    ?>

    `Using The API Client Library;`

    <?php
        require('nasaramobileapiclient.php');

        $smsApi = new NasaraMobileApiClient("your_api_key");
        $response = $smsApi->sendSms($phone, $senderId, $message);
    ?>

    from nasaramobileapiclient import NasaraMobileApiClient

    phone = "xxxxxxxxxxx"
    senderId = "Testing"
    message = "hey there, this is a test message!"

    smsApi = NasaraMobileApiClient("9EEPC38Eyf9N6Mc8beMEH")
    response = smsApi.sendSms(phone, senderId, message)


    require 'nasaramobileapiclient'

    phone = "xxxxxxxxxxx"
    senderId = "Testing"
    message = "hey there, this is a test message!"

    smsApi = NasaraMobileApiClient.new("your_api_key")
    response = smsApi.sendSms(phone, senderId, message)

To send a message, make a GET request using the url below. Replace relevant information with yours

HTTP Request

http://sms.nasaramobile.com/api?api_key=xxxx&sender_id=xxxx&phone=xxxxx&message=your%message

Version 2

HTTP Request

POST http://sms.nasaramobile.com/api/v2/sendsms


    <?php
        require('nasaramobileapiclient.php');

        $smsApi = new NasaraMobileApiClient("your_api_key");
        $response = $smsApi->sendSmsVersionTwo($phoneNumbers, $senderId, $message);

    ?>


Response;

{
  "status": 200,
  "code": 1816,
  "data": null,
  "message": "Messages processed successfully!",
  "url": "http://nasarasms.dev/api/v2/sendsms?api_key=567c1299197d5567c1299197e1&phone_numbers=233244209193&sender_id=RashKoKo&message=hello%20my%20friends!&groups=112,116&contacts=297367,297368,297369"
}


    from nasaramobileapiclient import NasaraMobileApiClient
    import json

    phoneNumbers = "233xxxxxxxxx, 24342xxxxxx"
    contactIds = "23,45,75,333,667,656,7878,898"
    senderId = "NTesting"
    message = "hey there, this is a test message!"


    smsApi = NasaraMobileApiClient("your_api_key")
    response = smsApi.sendSmsVersionTwo(phoneNumbers, senderId, message, none, contactIds)
    response = json.loads(response)

    require 'nasaramobileapiclient'
    require 'rubygems'
    require 'json'

    phoneNumbers = "233xxxxxxxxx, 24342xxxxxx"
    groups = "7782,324324,23545,23333"
    contactIds = "23,45,75,333,667,656,7878,898"
    senderId = "NTesting"
    message = "hey there, this is a test message!"

    smsApi = NasaraMobileApiClient.new("your_api_key")
    response = smsApi.sendSmsVersionTwo(phoneNumbers, senderId, message, groups, contactIds)
    response = JSON.parse(response)

This request requires the following parameters;

Arguments

Parameter Info Description
api_key required Needed to authenticate request
phone_numbers optional The phone numbers to message. Multiple numbers seperated by commas (eg.23423434390,23545645457645,435435345454)
contact_ids optional The ids of the contacts to message. Multiple contacts separated by commas. (eg. 123,6507,3454,232223,5654675). You can get your contact ids by making a GET API request for contacts
groups optional The ids groups you would like to message. Multiple groups separated by commas. (eg. 345345,657657,45465)
message required The text message to send. Message should be URL enconded
sender_id required The sender ID is an alphanumeric text with a maximum of eleven (11) characters. This could be a number or the name of the sender

Check Account Credit

Version 1


{"status":"1000","data":"72837"}

    <?php
        $url = "http://sms.nasaramobile.com/api/accounts/credit?api_key=$api_key";
        $response = file_get_contents($url);

        $result = json_decode($response);
        $credit = $result->data;
    ?>

You can check your SMS credit via the API. Error codes are returned alone while the data is returned in json format. Data contains the credit.

HTTP Request

GET : http://sms.nasaramobile.com/api/accounts/credit

Parameter Info Description
api_key required Needed to authenticate request

Version 2


{
    "status": 200,
    "code": 1818,
    "data": "72837",
    "message": "Account credit fetched successfully",
    "url": "http://sms.nasaramobile.com/api/v2/accounts/credit?api_key=xxxxxxxx"
}

<?php

        require_once('nasaramobileapiclient.php');

        $smsApi = new NasaraMobileApiClient("api_key");
        $response = $smsApi->checkCredit();

        $results = json_decode($response);
        echo $credit = $results->data;

    ?>
    from nasaramobileapiclient import NasaraMobileApiClient

    smsApi = NasaraMobileApiClient("9EEPC38Eyf9N6Mc8beMEH")
    smsApi.checkCredit

    require 'nasaramobileapiclient'

    smsApi = NasaraMobileApiClient.new("9EEPC38Eyf9N6Mc8beMEH")
    smsApi.checkCredit

HTTP Request

GET : http://sms.nasaramobile.com/api/v2/accounts/credit

Parameter Info Description
api_key required Needed to authenticate request

Contacts

Get All Contacts

JSON response


{
  "status": 200,
  "code": 1808,
  "data": {
    "contacts": [
      {
        "id": "297367",
        "name": "Tungteeya Amandi",
        "phone": "244209193",
        "email": "",
        "created_at": {
          "date": "2015-11-14 16:42:24.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "updated_at": {
          "date": "2015-11-14 16:42:24.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        }
      },
      {
        "id": "297368",
        "name": "Adam Eve",
        "phone": "78678676",
        "email": "",
        "created_at": {
          "date": "2015-11-14 16:42:24.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "updated_at": {
          "date": "2015-11-14 16:42:24.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        }
      }
    ]
  },
  "message": "Contacts fetched successfully!",
  "url": "http://sms.nasaramobile.com/api/v2/contacts/?api_key=567c1299197d5567c1299197e1"
}

<?php
  require_once('../nasaramobileapiclient.php');

  $smsApi = new NasaraMobileApiClient("9EEPC38Eyf9N6Mc8beMEH");
  $response = $smsApi->fetchContacts();

  print_r($response);
?>
  require 'nasaramobileapiclient'

  smsApi = NasaraMobileApiClient.new("9EEPC38Eyf9N6Mc8beMEH")
  smsApi.fetchContacts

  from nasaramobileapiclient import NasaraMobileApiClient

  smsApi = NasaraMobileApiClient("9EEPC38Eyf9N6Mc8beMEH")
  smsApi.getContacts()

This endpoint enables you to fetch all contacts from your account.

GET : http://sms.nasaramobile.com/api/v2/contacts

Parameter Info Description
api_key required Needed to authenticate request

Response Attributes

Attribute Description
id the contact id
name name of the contact
phone the contact’s phone number
email contacts’s email
created_at date created
updated_at date updated

Get Contact Details

{
  "status": 200,
  "code": 1811,
  "data": {
    "contacts": {
      "id": "297367",
      "name": "Rashkeed",
      "phone": "244209193",
      "email": "",
      "created_at": {
        "date": "2015-11-14 16:42:24.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2015-11-14 16:42:24.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    }
  },
  "message": "Contact details fetched successfully!",
  "url": "http://sms.nasaramobile.com/api/v2/contacts/297367?api_key=567c1299197d5567c1299197e1"
}

<?php
  require_once('nasaramobileapiclient.php');

  $smsApi = new NasaraMobileApiClient("9EEPC38Eyf9N6Mc8beMEH");
  $response = json_decode($smsApi->fetchContactDetails(337));

  print_r($response->data->contact);
?>

  require 'nasaramobileapiclient'

  smsApi = NasaraMobileApiClient.new("9EEPC38Eyf9N6Mc8beMEH")
  smsApi.fetchContactDetails(337)


  from nasaramobileapiclient import NasaraMobileApiClient

  smsApi = NasaraMobileApiClient("9EEPC38Eyf9N6Mc8beMEH")
  smsApi.getContactDetails()

This endpoint retrieves information for a specific contact

GET : http://sms.nasaramobile.com/api/v2/contacts/{contact_id}

Parameter Info Description
api_key required Needed to authenticate request

Response Attributes

Attribute Description
id the contact’s id
name name of the contact
phone the contact’s phone number
email contacts’s email
created_at date created
updated_at date updated

Groups

Get All Groups

JSON response


{
  "status": 200,
  "code": 1812,
  "data": {
    "groups": [
      {
        "id": "112",
        "name": "My Friends",
        "description": "Friend!",
        "total_number_of_contacts": "2",
        "created_at": {
          "date": "2013-06-15 21:58:05.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "updated_at": {
          "date": "2015-12-24 15:31:42.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        }
      },
      {
        "id": "113",
        "name": "Royal House Chapel, Kuma",
        "description": "Members of ROSA KNUST",
        "total_number_of_contacts": "0",
        "created_at": {
          "date": "2013-06-15 21:59:19.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        },
        "updated_at": {
          "date": "2013-11-17 16:56:14.000000",
          "timezone_type": 3,
          "timezone": "UTC"
        }
      }
    ]
  },
  "message": "Groups fetched successfully!",
  "url": "http://sms.nasaramobile.com/api/v2/groups?api_key=567c1299197d5567c1299197e1"
}

This endpoint enables you to fetch all contacts from your account.

GET : http://sms.nasaramobile.com/api/v2/groups

Parameter Info Description
api_key required Needed to authenticate request

Response Attributes

Attribute Description
id the group id
name name of the group
phone the group’s phone number
description group description
created_at date created
updated_at date updated

Get Group Details

{
  "status": 200,
  "code": 1815,
  "data": {
    "group": {
      "id": "113",
      "name": "Royal House Chapel, Kuma",
      "description": "Members of ROSA KNUST",
      "total_number_of_contacts": "0",
      "created_at": {
        "date": "2013-06-15 21:59:19.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      },
      "updated_at": {
        "date": "2013-11-17 16:56:14.000000",
        "timezone_type": 3,
        "timezone": "UTC"
      }
    }
  },
  "message": "Group details fetched successfully!",
  "url": "http://sms.nasaramobile.com/api/v2/groups/113?api_key=567c1299197d5567c1299197e1"
}

This endpoint retrieves information for a specific contact

GET : http://sms.nasaramobile.com/api/v2/groups/{group_id}

Parameter Info Description
api_key required Needed to authenticate request

Response Attributes

Attribute Description
id the group id
name name of the group
phone the group’s phone number
description group description
created_at date created
updated_at date updated

Errors & Status Codes

The Nasara Mobile API uses the following error and status codes:

Code Meaning
1801 message sent successfully
1802 message sending failed
1803 invalid api key
1804 not enough credit
1805 sender id must be more than 1 charater and less than 12 characters
1806 phone number must be more than 8 characters
1807 message not posted
1808 Contacts fetched successfully!
1809 Error fetching contacts
1810 There was a problem getting details for the given contact ID.
1811 Contact details fetched successfully!
1812 Groups fetched successfully!
1813 error fetching groups
1814 error fetching group details
1815 group details fetched successfully
1816 messages processed successfully
1817 Error processing messages
1818 account credit fetched successfully
Code Meaning
200 Successful Request
400 Bad Request
401 Unauthorized – Your API key is wrong
403 Forbidden – The API requested is hidden for administrators only
404 Not Found – The specified request could not be found
405 Method Not Allowed – You tried to access a request with an invalid method
406 Not Acceptable
410 Gone – The API call requested has been removed from our servers
429 Too Many Requests – Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.