Hubtel Developers

Suggest Edits

Online Checkout

 

Hubtel Online Checkout API gives your customers a simple checkout page for them to enter their mobile money wallet or bank card details. You do not need to worry about how to secure customer card or mobile money details.

The API presents RESTful endpoints that make it easy to integrate online payment into any application.

To use this API, you are required to activate a merchant account on Hubtel. You also need to upload business verification documents before you can transfer your funds out into your sweep account. This is needed for Know Your Customer (KYC) requirements and also helps to keep your account safe from unauthorised access.

Authentication

Requests to the checkout API endpoints are authenticated using Basic Authentication. This requires you to provide a Base 64 encoding of your Client ID as your username and Client Secret as your password. You can easily create API keys on your Hubtel account.

Suggest Edits

Create Checkout Invoice

This enables you to create a checkout invoice by providing the necessary details to redirect your customers to checkout using mobile money or debit/credit card. After making payment customers are redirected to your website.

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.hubtel.com/v2/pos/onlinecheckout/items/initiate
{
  "items": [
    {
      "name": "Harry Potter",
      "quantity": 1,
      "unitPrice": 50
    },
    {
      "name": "Chinua Achebe",
      "quantity": 1,
      "unitPrice": 50
    }
  ],
  "totalAmount": 100,
  "description": "Book Shop Checkout",
  "callbackUrl": "https://webhook.site/8b4bbd0a-5f98-4b3d-abbe-b9b49767f7d5",
  "returnUrl": "http://hubtel.com/online",
  "merchantBusinessLogoUrl": "http://hubtel.com/online",
  "merchantAccountNumber": "HM2511160001",
  "cancellationUrl": "http://hubtel.com/online",
  "clientReference": "inv0012"
}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
  {
  "responseCode": null,
  "status": "Success",
  "data": {
    "checkoutUrl": "http://plt-checkout-v2.hubtel.com/f2c339ed-fda1-4dd5-8cfc-9544833aae42",
    "checkoutId": "f2c339ed-fda1-4dd5-8cfc-9544833aae42",
    "clientReference": "inv0012",
    "message": ""
  }
}

Body Params

invoice
object
 
invoice.items
array of objects
required

The invoice items object specifies the list of items to display on the invoice page.

name
quantity
unit_price
itemImageUrl
totalAmount
string
required

Specifies the total amount expected to be paid for the Items being purchased.

description
string
required

describes to customers actions they can perform on the checkout page

callbackUrl
string
required

The callback URL registered to receive the final notification on the status of the payment.

returnUrl
string
required

The merchant website URL where the customer should return after payment.

cancellationUrl
string
required

The merchant website URL where the customer should return after cancellation.

merchantBusinessLogoUrl
string
required

The merchant business logo URL. The dimensions should ideally be a 100px X 100px.

merchantAccountNumber
string
required

The Hubtel Merchant account number.

clientReference
string
required

A unique string identifying the request. Useful for reference purposes. It cannot be empty but must have a maximum of 10 characters.

 
Suggest Edits

Checkout Callback

 

You are required to implement a callback endpoint on your server to receive payment notification status on the payment or the order notification status.

We recommend using services like Webhook Tester, Request Catcher or ngrok to test your webhook callbacks. These services allow you to define temporary dummy endpoints which will show you the requests and all the data you are receiving from Hubtel.

Provide the dummy URL as the value for the PrimaryCallbackUrl or SecondaryCallbackUrl parameter.

Sample Payment Status

  POST https://webhook.site/a8b36a02-5272-4a56-8e2b-15eab5e6bb71 HTTP/1.1
  Host: webhook.site
  Content-Type: application/json
  Cache-Control: no-cache
{
  "ResponseCode": "0000",
  "Status": "Success",
  "Data": {
    "CheckoutId": "99bb18b5-0745-4de7-ac08-72665431e40b",
    "SalesInvoiceId": "9f7d11d4d5d44d6eb5a159e6c47dcaec-20180518131450758",
    "ClientReference": "9246158385",
    "Status": "Success",
    "Amount": 600,
    "CustomerPhoneNumber": "+233541719387",
    "PaymentDetails": {
      "MobileMoneyNumber": "+233541719387",
      "PaymentType": "MobileMoney"
    },
    "Description": "Invoice paid successfully"
  }
}

Sample Order Status

  POST https://webhook.site/a8b36a02-5272-4a56-8e2b-15eab5e6bb71 HTTP/1.1
  Host: webhook.site
  Content-Type: application/json
  Cache-Control: no-cache
{
  "ResponseCode":"0002",
    "Status":"Success",
    "Data":
      {
       "CheckoutId":"14a2c65b-1f06-4114-9cf1-b54ffb30955c",
       "SalesInvoiceId":"50abe4d2e07d45cca3093f278389036b-20180906140313240",
       "ClientReference":"32weqewa",
       "Status":"Ordered",
       "Amount":1.0,
       "CustomerPhoneNumber":"+233243019231",
       "PaymentDetails":null,
       "Description":"customer has placed an order",
       "OrderNumber":"0000115",
       "OrderToken":"246fd0286820471d9013f2d76f446569-20180906140406289"
      }
}
Suggest Edits

Response Codes

The Hubtel Payment API uses standard HTTP error reporting. Successful requests return HTTP status codes in the 2xx. Failed requests return status codes in 4xx and 5xx. Response codes are included in the JSON response body, which contain information about the response.

 
Response Code
Description
Action Required

0000

The transaction has been processed successfully.

0001

Merchant account is not available.

Ensure that your're providing the correct Basic Auth key for the Authorization header. See authentication above for more details.

0002

The Order has been processed successfully. Payment will have to be completed manually as a cash sale after delivery.

4105

Authenticated hubtel organisation not owner of specified account number.

There's a mismatch of the Merchant Account number and the the Basic Authorisation key. Ensure your API keys are from the same Unity account as the Merchant Account.

2050

The MTN Mobile Money user has insufficient funds in wallet to make this payment.

Customer has to top up mobile money wallet with funds more than the amount being charged.

2051

The mobile number provided is not registered on MTN Mobile Money.

Ensure that the mobile number is registered on the MTN channel.

2100

The request failed as the customer's phone is switched off.

2101

The transaction failed as the PIN entered by the Airtel Money customer is invalid.

2102

The Airtel Money user has insufficient funds in wallet to make this payment.

2103

The mobile number specified is not registered on Airtel Money.

2152

The mobile number specified is not registered on Tigo cash.

2153

The amount specified is more than the maximum allowed by Tigo Cash.

2154

The amount specified is more than the maximum daily limit allowed by Tigo Cash.

2200

The recipient specified is not registered on Vodafone Cash.

2201

The customer specified is not registered on Vodafone Cash.

Suggest Edits

Transaction Status Check

This allows a merchant to check for the current status of a transaction by providing a transaction identifier. A query to this endpoint returns the status of a mobile money or an online checkout transaction along with extra transaction data.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.hubtel.com/v1/merchantaccount/merchants/MerchantAccountNumber/transactions/status?invoiceToken=InvoiceToken&networkTransactionId=NetworkTransactionId&hubtelTransactionId=HubtelTransactionId
curl --request GET \
  --url 'https://api.hubtel.com/v1/merchantaccount/merchants/MerchantAccountNumber/transactions/status?hubtelTransactionId=HubtelTransactionId&networkTransactionId=NetworkTransactionId&invoiceToken=InvoiceToken'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.hubtel.com/v1/merchantaccount/merchants/MerchantAccountNumber/transactions/status',
  qs: 
   { hubtelTransactionId: 'HubtelTransactionId',
     networkTransactionId: 'NetworkTransactionId',
     invoiceToken: 'InvoiceToken' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.hubtel.com/v1/merchantaccount/merchants/MerchantAccountNumber/transactions/status?hubtelTransactionId=HubtelTransactionId&networkTransactionId=NetworkTransactionId&invoiceToken=InvoiceToken")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

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

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

xhr.open("GET", "https://api.hubtel.com/v1/merchantaccount/merchants/MerchantAccountNumber/transactions/status?hubtelTransactionId=HubtelTransactionId&networkTransactionId=NetworkTransactionId&invoiceToken=InvoiceToken");

xhr.send(data);
import requests

url = "https://api.hubtel.com/v1/merchantaccount/merchants/MerchantAccountNumber/transactions/status"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Body Params

invoiceToken
string

The invoice token generated from an online checkout.

networkTransactionId
string

The mobile money provider's transaction id.

hubtelTransactionId
string

The transaction id provided by Hubtel.

 

Sample Request

GET /v1/merchantaccount/merchants/HMXXXXXXXXXX/transactions/status?networkTransactionId={TransactionId} HTTP/1.1
Host: api.hubtel.com
Accept: application/json
Content-Type: application/json
Authorization: Basic endjeOBiZHhza250cG4=
Cache-Control: no-cache

Sample Response 

{
    "ResponseCode": "0000",
    "Data": [
        {
            "StartDate": "2017-08-23T15:35:17.967",
            "TransactionStatus": "Settled",
            "TransactionId": "8606d5b0c50342c6a35f40fdb95bde78",
            "NetworkTransactionId": "1846027922",
            "InvoiceToken": "57229a472e7f4eae",
            "TransactionType": "RECEIVE-MONEY",
            "PaymentMethod": "MOBILE-MONEY",
            "ClientReference": "DTX589298",
            "CountryCode": "GH",
            "CurrencyCode": "GHS",
            "TransactionAmount": 0.5,
            "Fee": 0.05,
            "AmountAfterFees": 0.45,
            "CardSchemeName": null,
            "CardNumber": null,
            "MobileNumber": "233574126849",
            "MobileChannelName": "tigo-gh",
            "TransactionCycle": [
                {
                    "Date": "2017-08-24T00:00:05.427",
                    "Status": "Settled"
                },
                {
                    "Date": "2017-08-23T15:36:47.277",
                    "Status": "Success"
                },
                {
                    "Date": "2017-08-23T15:35:17.967",
                    "Status": "Pending"
                }
            ],
            "RelatedTransactionId": null,
            "RelatedTransactionType": null,
            "Disputed": false,
            "DisputedAmount": 0,
            "DisputedAmountFee": 0,
            "TotalAmountRefunded": 0
        }
    ]
}
Suggest Edits

USSD Push Request

The Hubtel USSD API pushes USSD requests to the application URL you specify in your Hubtel account.

 
posthttp://yourhostname.com/ussd-app
{
   "Type":"Initiation",
   "Mobile":"233244123456",
   "SessionId":"bb3aece1deb543009c9f35b943c74b7f",
   "ServiceCode":"714",
   "Message":"*714#",
   "Operator":"Vodafone",
   "Sequence":1,
   "ClientState":null
}

//Download Google Gson: A Java serialization/deserialization library that can convert Java Objects into JSON and back. 
package com.smsgh;

import java.io.IOException;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

import com.google.gson.Gson;

public class HelloUssdServlet extends HttpServlet {

    /*
     * Not needed by USSD API.
     */
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        resp.setContentType("text/plain");
		resp.getWriter().println("Hello USSD!");
    }

    /**
     * USSD API request is received as a POST request.
     */
    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        // Use Gson JSON library to read and parse JSON request.
        Gson gson = new Gson();
        UssdRequest ussdRequest = gson.fromJson(req.getReader(), UssdRequest.class);
        
        // Log request in server's logs.
        getServletContext().log("Received USSD request: " + ussdRequest);
        
        // Since this is just a demo, release USSD session with a "Hello" message
        // to the mobile phone user.
        UssdResponse ussdResponse = new UssdResponse("Release",
            "Hello USSD! To: " + ussdRequest.Mobile);
        
        // USSD API accepts and requires JSON, so set content type accordingly.
        resp.setContentType("application/json");
        
        // Generate and send JSON response.
        String ussdResponseJson = gson.toJson(ussdResponse);
        resp.getWriter().print(ussdResponseJson);
    }      
}

class UssdRequest
{
    public String Type;
    
    public String Message;
    
    public String Operator;
    
    public String SessionId;
    
    public String Mobile;
    
    public int Sequence;
    
    public String ClientState;
    
    public String ServiceCode;
    
    @Override 
    public String toString() {
        return String.format("UssdRequest" +
            "[Mobile=%s, SessionId=%s, " +
            "Type=%s, Message=%s, Operator=%s, " +
            "Sequence=%s, ClientState=%s, ServiceCode=%s]",
            Mobile, SessionId, Type, Message, Operator, Sequence,					
                ClientState, ServiceCode);
    }
}

class UssdResponse
{    
    public String Type;
    
    public String Message;
    
    public String ClientState;
    
    public UssdResponse() {}
    
    public UssdResponse(String type, String message)
    {
        this.Type = type;
        this.Message = message;
    }
}            

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Web;
using System.Web.Helpers;
using System.Web.Mvc;

namespace HelloUssd.Controllers
{
    public class HelloUssdController : Controller
    {
        // GET: HelloUssd. Not needed by USSD API.
        public ActionResult Index()
        {
            return new ContentResult
            {
                ContentType = "text/plain",
                Content = "Hello USSD!"
            };
        }

        // POST: HelloUssd. USSD API request is received as a POST request.
        [HttpPost]
        [ActionName("Index")]
        public ActionResult IndexPost()
        {
            // Fetch request body as a string.
            BinaryReader inputStreamReader = new BinaryReader(Request.InputStream);
            byte[] requestBytes = inputStreamReader.ReadBytes(Request.ContentLength);
            string requestString = Request.ContentEncoding.GetString(requestBytes);
                            
            // Parse JSON request.
            UssdRequest ussdRequest = System.Web.Helpers.Json.Decode(requestString);

            // Since this is just a demo, release USSD session with a "Hello" message
            // to the mobile phone user.
            var resp = new { Type = "Release", Message = "Hello USSD! To: " + ussdRequest.Mobile };

            // USSD API accepts and requires JSON, so generate and send JSON response.
            return Json(resp);
        }
    }

    class UssdRequest
    {
        public String Type;

        public String Message;

        public String Operator;

        public String SessionId;

        public String Mobile;

        public int Sequence;

        public String ClientState;

        public String ServiceCode;
    }
}


header('Content-type: application/json; charset=utf-8'); 
$ussdRequest = json_decode(@file_get_contents('php://input')); 

    // Check if no errors occured. 
    if ($ussdRequest != NULL) { 

    // Create a response object. 
    $ussdResponse = new stdClass; 

    // Set the message to display. 
    $ussdResponse->Message = "Hello world $ussdRequest->Mobile"; 

    // Set the type of this response. 
    $ussdResponse->Type = "Release"; 

  // Encode the response object as JSON and send. 
  echo json_encode($ussdResponse); 
}
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "Message": "Welcome James Thompson. \n 1.Check Balance 2.Change PIN 3.Request Support.",
    "Type": "Response",
    "ClientState": null
}

Body Params

Mobile
string
required

Represents the phone number of the mobile subscriber.

SessionId
string
required

UUID string representing a unique identifier for the current USSD Session.

ServiceCode
string
required

Represents the USSD Service code assigned by the network.

Type
string
required

Indicates the type of USSD Request. Possible values are: Initiation:: indicates the first message in a USSD Session. Response:: indicates the subsequent response in an already existing USSD session. Release:: indicates that the subscriber is ending the USSD session. Timeout:: indicates that the USSD session has timed out.

Message
string
required

Represents the actual text entered by the mobile subscriber. For initiation, this will represent the USSD string entered by the subscriber. For Response, this will be the message sent.

Operator
string
required

Indicates the network operator the subscriber belongs to: Tigo, Airtel, MTN ,Vodafone, Safaricom

Sequence
int32
required

Indicates the position of the current message in the USSD session.

ClientState
string

Represents data that API client asked API service to send from the previous USSD request. This data is only sent in the current request and is then discarded.

 

More Examples

Typical USSD Session for checking account balance on a simple banking USSD App.

The User dials short code for a linked banking app. *711#. The Hubtel USSD API sends the following request to the Client Resource:

POST 
Content-Type: application/json
Accept: application/json

{
    "Mobile": "233262183777",
    "SessionId": "8883ba8b1e7348b8b566b4b3396575d5",
    "ServiceCode": "711",
    "Type": "Initiation",
    "Message": "*711#",
    "Operator": "vodafone",
    "Sequence": 1
    "ClientState": null,
}

The application responds by sending out a menu requesting for pin

{
    "Type": "Response",
    "Message" : "Enter your pin",
    "ClientState": "2017-03-30",
    "MaskNextRoute": true  
}

The User responds to menu invitation by entering pin. The Hubtel USSD API sends the following request to the Client Resource:

POST 
Content-Type: application/json
Accept: application/json

{
    "Mobile": "233262183777",
    "SessionId": "8883ba8b1e7348b8b566b4b3396575d5",
    "ServiceCode": "711",
    "Type": "Response",
    "Message":  "1234",
    "Operator":"vodafone",
    "Sequence": 2,
    "ClientState":"2018-08-14"
}

The application responds by sending out a menu with multiple options

{
    "Message": "Dear Customer \n1. Account Balance \n2. Mini Statement",
    "Type": "Response", 
    "MaskNextRoute": true, 
}

The User responds to menu invitation by entering "1". The Hubtel USSD API sends the following request to the Client Resource:

POST 
Content-Type: application/json
Accept: application/json

{
    "Mobile": "233262183777",
    "SessionId": "8883ba8b1e7348b8b566b4b3396575d5",
    "ServiceCode": "711",
    "Type": "Response",
    "Message":  "1",
    "Operator":"vodafone",
    "Sequence": 3,
    "ClientState":null
}

The application responds by sending out a menu with multiple options

{
    "Message": "Your account balance is GHS 53,743",
    "Type": "Release", 
    "Mask": true, 
}
Suggest Edits

USSD Error Codes

The USSD Gateway throws an error if a USSD request is not processed appropriately, a system generated error message is sent to the mobile user. Below are the possible messages and their causes.

 
Error Code
Description

URNF

Your setup is not complete. Please raise a Ticket on your account or email support@hubtel.com for assistance.

UUT

Our attempt to reach your application URL has timed out. Optimize your application and ensure that it is responding to requests within 7 seconds.

ST

The application took too long to respond. Either the app is too slow, or the subscriber took too long to respond to the USSD prompt. Please note that subscribers must respond within 60 seconds.

UUE

Your application is not responding with a valid JSON response. Check to see if your JSON response is valid.

NOCR

Your service is currently unavailable because you are out of credit on your Unity account. Top up your account here.

NOAPP

Your application is not yet mapped to any USSD Service Code. You can map your app URL here.

CSP

Hubtel is unable to forward your request to our upstream provider for onward processing. Contact support@hubtel.com for assistance.

There are also Errors which will emanate from the Network Operator. A few of the errors which can be encountered are:

NETWORK ERROR CODE
DESCRIPTION

SERVICE UNAVAILABLE

The Network Provider is unable to display the USSD Menu because the service is not available.

UNABLE TO DISPLAY USSD

The Network Provider is unable to display the USSD Menu.

ERROR AT WASP E150

The Network Provider gives a negative response to the USSD Application.

REQUEST FAILS

The Network Provider does not recognise the USSD code.

ERROR WAP

The Network Provider is unable to process Code now.

Suggest Edits

Sending Messages

 
Suggest Edits

Quick Send

Waste no time installing SDK. Try out the Quick API.

 
gethttps://api.hubtel.com/v1/messages/send?FromToContentClientIdClientSecretRegisteredDelivery
curl --request GET \
  --url 'https://api.hubtel.com/v1/messages/send?From=From&To=To&Content=Content&ClientID=ClientID&ClientSecret=ClientSecret&FromToContentClientIdClientSecretRegisteredDelivery='
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.hubtel.com/v1/messages/send',
  qs: 
   { From: 'From',
     To: 'To',
     Content: 'Content',
     ClientID: 'ClientID',
     ClientSecret: 'ClientSecret',
     FromToContentClientIdClientSecretRegisteredDelivery: '' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.hubtel.com/v1/messages/send?From=From&To=To&Content=Content&ClientID=ClientID&ClientSecret=ClientSecret&FromToContentClientIdClientSecretRegisteredDelivery=")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

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

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

xhr.open("GET", "https://api.hubtel.com/v1/messages/send?From=From&To=To&Content=Content&ClientID=ClientID&ClientSecret=ClientSecret&FromToContentClientIdClientSecretRegisteredDelivery=");

xhr.send(data);
import requests

url = "https://api.hubtel.com/v1/messages/send"

querystring = {"From":"From","To":"To","Content":"Content","ClientID":"ClientID","ClientSecret":"ClientSecret","FromToContentClientIdClientSecretRegisteredDelivery":""}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
    "Status": 0,
    "MessageId": "0d225943d1844829b6a154aeb1d1671d",
    "Rate": 1,
    "NetworkId": "62001",
    "ClientReference": "1234"
}

Query Params

From
string
required

The sender address. In case it is a telephone number it must comply with the telephone rules.

To
string
required

The recipient telephone number. It must comply with the telephone rules.

Content
string
required

The message content

ClientID
string
required

Your Unity API Client ID

ClientSecret
string
required

Your Unity API Client secret

RegisteredDelivery
boolean

A true or false setting to indicate a delivery report request

 
Suggest Edits

Send Message

Send Message API helps you reach your customers with information. Improve your customer service with Hubtel Send Message API.

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.hubtel.com/v1/messages
curl --request POST \
  --url https://api.hubtel.com/v1/messages
var request = require("request");

var options = { method: 'POST', url: 'https://api.hubtel.com/v1/messages' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.hubtel.com/v1/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

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

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

xhr.open("POST", "https://api.hubtel.com/v1/messages");

xhr.send(data);
import requests

url = "https://api.hubtel.com/v1/messages"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 201 Created
Content-Length: 102
Content-Type: application/json; charset=utf-8
Location: https://api.hubtel.com/v1/messages/43cceb19d2a242f58fb338692e12c0bb
Server: Microsoft-HTTPAPI/2.0
Date: Tue, 13 Aug 2013 14:41:26 GMT

{
    "Status": 0,
    "MessageId": "43cceb19d2a242f58fb338692e12c0bb",
    "Rate": 0,
    "NetworkId": "0"
}

Body Params

Type
int32

Indicates the type of message to be sent. Possible values are: Unset(default) 0 - Text message 1 - Binary message 2 - Unicode based message

From
string
required

The sender address.Sender IDs must be 11 characters or less without spaces or 16 numbers.

To
string
required

The recipient telephone number. This number must be in the international telephone number format with a "+" as prefix. National numbers may be used if there is a guarantee that the Country Code set is valid for the recipient number. For example when the user’s country is “United States”, it is possible to send messages to the phone number "773-409-4910". The number must be a valid phone number

Content
string
required

The body of the message. This is required for all message types except WAP Push messages. Binary messages should use HEX string notation

Udh
string

The User Data Header of the SMS Message being sent. Udh must be HEX string notation.

Direction
string

Indicates if the message originated from this API ("out") or originated from a mobile subscriber ("in"). This attribute is only displayed in response to a query. Possible Values are "in" and "out".

Time
date-time

The is automatically converted to GMT, in case you want it in UTC, kindly change it in your Unity Account.

UpdateTime
date-time

Indicates when the message was last updated. Usually when the last delivery report was received on the message.

NetworkId
string

The unique ID for the mobile network a combination of MCC and MNC for this message.

ClientReference
string

A reference set by the client for uniquely identifying this message. The client reference will be sent as part of delivery report notifications.

RegisteredDelivery
boolean

A true or false setting to indicate a delivery report request.

Units(readonly)
int32

The number of parts or units of this message.

Rate(readonly)
int32

The total cost of this message. The default rate plan is messaging credit. Users on a service postpaid plan may have the rates defined in local currency.

Status(readonly)
string

The current delivery status of this SMS message.

FlashMessage
boolean

A true or false value indicating if this message must be sent as a flash message.

 
Suggest Edits

Get Message

You may want to know the details or the status of a particular message that you have sent in the past. Get Message API makes it possible in a simple way.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.hubtel.com/v1/messages/messageId
curl --request GET \
  --url https://api.hubtel.com/v1/messages/messageId
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.hubtel.com/v1/messages/messageId' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.hubtel.com/v1/messages/messageId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

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

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

xhr.open("GET", "https://api.hubtel.com/v1/messages/messageId");

xhr.send(data);
import requests

url = "https://api.hubtel.com/v1/messages/messageId"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}

HTTP/1.1 200 Ok
Content-Length: 282
Content-Type: application/json; charset=utf-8
Server: Microsoft-HTTPAPI/2.0
Date: Tue, 29 Aug 2017 08:16:48 GMT

{
    "MessageId": "6f19395db2fb497ea4ebd1e218dd3e4c",
    "From": "Seinti",
    "To": "+233208183783",
    "Time": "2013-06-02 10:56:34",
    "UpdateTime": "2013-08-12 17:11:42",
    "NetworkId": "62001",
    "Units": 1,
    "Rate": 1,
    "Status": "Undeliverable",
    "Content": "hello, Kwadwo!"
}

Path Params

messageId
string
required

The Id of the message you want to retrieve

 
Suggest Edits

Query Message

We are sure you will want to retrieve all the messages you have sent so Query Message API has been provided to make it possible.

 

Basic Auth

 Authentication is required for this endpoint.
gethttps://api.hubtel.com/v1/messages
curl --request GET \
  --url https://api.hubtel.com/v1/messages
var request = require("request");

var options = { method: 'GET', url: 'https://api.hubtel.com/v1/messages' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.hubtel.com/v1/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

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

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

xhr.open("GET", "https://api.hubtel.com/v1/messages");

xhr.send(data);
import requests

url = "https://api.hubtel.com/v1/messages"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
GET /v1/messages?index=100&limit=2 HTTP/1.1
Host: api.hubtel.com
Accept: application/json
Authorization: Basic aWlocGtoZHU6bnZtdnp2bWY=
 
Suggest Edits

Schedule Message

You will want to send a message at a particular time, but you may not be available at that time to send. Our SMS API allows you to schedule the message to be sent at the desired time.

 

Basic Auth

 Authentication is required for this endpoint.
posthttps://api.hubtel.com/v1/messages
curl --request POST \
  --url https://api.hubtel.com/v1/messages
var request = require("request");

var options = { method: 'POST', url: 'https://api.hubtel.com/v1/messages' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.hubtel.com/v1/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

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

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

xhr.open("POST", "https://api.hubtel.com/v1/messages");

xhr.send(data);
import requests

url = "https://api.hubtel.com/v1/messages"

response = requests.request("POST", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
HTTP/1.1 201 Created
Content-Length: 102
Content-Type: application/json; charset=utf-8
Location: https://api.hubtel.com/v1/messages/43cceb19d2a242f58fb338692e12c0bb
Server: Microsoft-HTTPAPI/2.0
Date: Tue, 13 Aug 2017 14:41:26 GMT

{
    "Status": 0,
    "MessageId": "43cceb19d2a242f58fb338692e12c0bb",
    "Rate": 0,
    "NetworkId": "0"
}

Body Params

Type
string

Indicates the type of message to be sent. Possible values are: Unset(default) 0 - Text message 1 - Binary message 2 - Unicode based message

From
string
required

The sender address.Sender IDs must be 11 characters or less without spaces or 16 numbers

To
string
required

The recipient telephone number. This number must be in the international telephone number format with a "+" as prefix. National numbers may be used if there is a guarantee that the Country Code set is valid for the recipient number. For example when the user’s country is “United States”, it is possible to send messages to the phone number "773-409-4910". The number must be a valid phone number.

Content
string
required

The body of the message. This is required for all message types except WAP Push messages. Binary messages should use HEX string notation.

Time
date
required

The time at which you want the message to be sent

 
Suggest Edits

Reschedule Scheduled Message API

A message you scheduled can be rescheduled. This is done when the scheduled message failed or when you want to make changes to the time for the message to be sent earlier or later than the current time.

 

Basic Auth

 Authentication is required for this endpoint.
puthttps://api.hubtel.com/v1/messages/messageId
curl --request PUT \
  --url https://api.hubtel.com/v1/messages/messageId
var request = require("request");

var options = { method: 'PUT',
  url: 'https://api.hubtel.com/v1/messages/messageId' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.hubtel.com/v1/messages/messageId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

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

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

xhr.open("PUT", "https://api.hubtel.com/v1/messages/messageId");

xhr.send(data);
import requests

url = "https://api.hubtel.com/v1/messages/messageId"

response = requests.request("PUT", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
PUT /v1/messages/43cceb19d2a242f58fb338692e12c0bb HTTP/1.1
Host: api.hubtel.com
Accept: application/json
Authorization: Basic aWlocGtoZHU6bnZtdnp2bWY=
Content-Type: application/json
{
    "Time": "2017-08-09 05:00:00"
}

Path Params

messageId
date
required

Indicates when to send the message. It also indicates when a message was sent if this is an inbound message.

Body Params

Time
date
required

The time at which you would like to reschedule the message

 
Suggest Edits

Cancel Scheduled Message API

With this API, you can cancel a scheduled message that you no more want to send.

 

Basic Auth

 Authentication is required for this endpoint.
deletehttps://api.hubtel.com/v1/messages/messageId
curl --request DELETE \
  --url https://api.hubtel.com/v1/messages/messageId
var request = require("request");

var options = { method: 'DELETE',
  url: 'https://api.hubtel.com/v1/messages/messageId' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://api.hubtel.com/v1/messages/messageId")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Delete.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

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

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

xhr.open("DELETE", "https://api.hubtel.com/v1/messages/messageId");

xhr.send(data);
import requests

url = "https://api.hubtel.com/v1/messages/messageId"

response = requests.request("DELETE", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
{
  "Status": 0
}

Path Params

messageId
string
required

The Id of the scheduled message you want to delete

 
Suggest Edits

Receive Message API

 
Suggest Edits

Receive Message

In case you want to receive message from your subscribers, what you need is the Short Code API.

 
posthttps://myapp.myserver.com/message/?fromtofulltextkeywordtextaccountcampaigndatenetwork
curl --request POST \
  --url 'https://myapp.myserver.com/message/?from=from&to=to&fulltext=fulltext&keyword=keyword&text=text&account=account&campaign=campaign&network=network&fromtofulltextkeywordtextaccountcampaigndatenetwork='
var request = require("request");

var options = { method: 'POST',
  url: 'https://myapp.myserver.com/message/',
  qs: 
   { from: 'from',
     to: 'to',
     fulltext: 'fulltext',
     keyword: 'keyword',
     text: 'text',
     account: 'account',
     campaign: 'campaign',
     network: 'network',
     fromtofulltextkeywordtextaccountcampaigndatenetwork: '' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

require 'uri'
require 'net/http'

url = URI("https://myapp.myserver.com/message/?from=from&to=to&fulltext=fulltext&keyword=keyword&text=text&account=account&campaign=campaign&network=network&fromtofulltextkeywordtextaccountcampaigndatenetwork=")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

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

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

xhr.open("POST", "https://myapp.myserver.com/message/?from=from&to=to&fulltext=fulltext&keyword=keyword&text=text&account=account&campaign=campaign&network=network&fromtofulltextkeywordtextaccountcampaigndatenetwork=");

xhr.send(data);
import requests

url = "https://myapp.myserver.com/message/"

querystring = {"from":"from","to":"to","fulltext":"fulltext","keyword":"keyword","text":"text","account":"account","campaign":"campaign","network":"network","fromtofulltextkeywordtextaccountcampaigndatenetwork":""}

response = requests.request("POST", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{{ results.method }}
{{ results.url }}
{{ results.requestHeaders }}
{{ results.data }}
{{ results.responseHeaders }}
Try the API to see results

Query Params

from
string
required

The sender of the message

to
string
required

Recipient of the message

fulltext
string
required

The full text message including the keyword.

keyword
string
required

first word in the message

text
string
required

message without the keyword

account
string
required

your unity account Id

campaign
string
required

The unity campaign ID on which messages were received

date
date-time

message timestamp in the format YYYY-MM-DD HH:MM. For example the date will be formatted as (2009-05-24 18:00).

network
string
required

network MCC and MNC combination where known or only MCC otherwise. Refer to this article Mobile Country Code for more information

 

Event Data

Attribute
Type
Description

From

string

The sender of the message

To

string

Recipient of the message

MessageId

string

UUID (with no dashes). The ID of the message that was returned during sending operatio

ClientReference

string

The client reference that was used to send the message

Status

string

The status of the message. The following status are available:
Rejected
Submitted
Delivered
Buffered
Accepted
Undeliverable
Deleted
Expired
Received
Unknown
Error
Buffered Locally
Scheduled
Sent
Expired Locally
Out of Credit
SMSC Invalid
Blacklisted
Unrouteable
Exceeded Limited
Invalid Source Address
Invalid Destination Address
Invalid Message Length
Invalid Time
Invalid Message ID
Invalid Account ID/Number

Suggest Edits

Response Code

You will receive responses after sending a message and it is important for you to understand what each means. Below is a list of success and error codes you may get and their description.

 
Code
Subcode
Description

200

The request was successfully handled by the API

201

0

The request was successful and the message has been sent for onward delivery

100

General invalid request. Returned when no data is sent or a malformed request is received.

1

Invalid Destination address received. The recipient's phone number is not a valid phone number

2

Invalid Source address was sent. You need to be aware of the sender address restrictions.

3

The message body was too long.

400

4

The message is not routable on Hubtel gateway

5

The delivery time specified was not a valid time.

6

The message content was rejected or is invalid.

7

One or more parameters are not allowed in the message. Details will be provided as part of the response.

8

One or more parameters are not valid for the message. Details will be provided as part of the response.

401

The request authorization failed.

402

Your account does not have enough messaging credit to send the message.

403

Forbidden. It means that the recipient has not given his/her approval to receive messages.

404

The specified message was not found.

500

The request failed on the server.

502

Bad Gateway. The server could not find any appropriate gateway for the request.

Suggest Edits

Setting up OAuth

 
Suggest Edits

OAuth 2.0 Access for Your Application

 

Setting up OAuth 2.0 Access for Your Application

Setting up your app on the Unity Portal as a Public Application will enable it to make requests to the API using OAuth requests.
In order for your app to fully use OAuth 2 to access the Unity API, you need a firm grasp of the OAuth 2.0 concepts.

Tokens

OAuth is an authorization protocol that makes heavy use of tokens as a replacement for usernames and passwords. Users would otherwise have to provide your application with a new username and password anytime the passwords were changed. Tokens must be guarded just like how usernames and passwords are guarded.

The following tokens are of importance:

Authorization Code
An authorization code is a short-lived token created by the authorization server and passed to the client application via the web browser or web view components in some instances of native mobile applications. The client application sends the authorization code to the authorization server to obtain an access token and, a refresh token if your app is a Partner Application.

Access Token
The access token is used by the client to make authorized requests on behalf of the Unity user. It has a longer lifetime than the authorization code, typically on the order of minutes or hours. When the access token expires, attempts to use it will fail, and a new access token must be obtained. Partner applications can simply use the refresh token to obtain a new access token. Public applications however must go through the OAuth2 web flow.
The access tokens are long-lived for partner applications and will expire every 30 days. Public application access tokens have a much shorter expiration period of 3 hours; and will require the user to log in and re-authorize after expiry.

Refresh Token
Refresh tokens are used to obtain new access tokens. The refresh token may have a much longer validity time. The client application can store the refresh token, using it to periodically obtain fresh access tokens, but should be careful to protect it against unauthorized access, since, it can be repeatedly used to gain access to the resource server.

Refresh tokens may expire or be revoked by the user outside the control of the client application, the client must handle failure to obtain an access token, by passing the user through the entire OAuth 2 flow once again.
The idea of refresh tokens is that if an access token is compromised, because it is short-lived, the attacker has a limited window in which to abuse it.
Refresh tokens, if compromised, are useless because the attacker requires the client id and secret in addition to the refresh token in order to gain an access token.

Handling OAuth Errors
Your application must be able to handle exceptional scenarios when things go wrong. Errors may happen at both the authorization and token steps. Errors are turned with two attributes:

Attributes
Description

Error

The error code or short name

Error_description

A detailed description of the error

Common Errors:

Error
Description

Invalid Client

This error occurs when either the client ID, or client secret is not valid. It may also occur in cases where your app has been suspended.

Invalid Redirect URLs(Not the same as the default URL)

The redirect URI does not match what you have set as your default callback.

Access Denied

The user has declined access for your application.

Invalid Authorization Code/Invalid Refresh Code

The authorization code is either invalid or has been used. The refresh token may also have expired or has been revoked by the user

Bad Request

This usually means one or more required parameters is missing from your request.

Handle App De-Authorizations

Users may occasionally de-authorize or uninstall your app from their Hubtel Unity account. When this happens, we will notify you by making an HTTP GET request to your De-Authorization Callback URL specified under your app’s public details. This URL will only be called if you have specified it.

When this happens we will make the following request:

GET https://app.example.com/oauth_deauthorize:
The URL above is an example substituting your actual URL.

Parameters

Name
Type
Description

access_token

string

Your application's access token.

Suggest Edits

Authorizing Web Server Based Applications - OAuth 2.0 Web Server Flow

 

In order for third-party web applications to get access to a Unity user’s account, the application must be authorized using an OAuth web flow. This method depends on the security of you web server. It is assumed that you application will securely store both access tokens and web tokens. The following steps describe how to implement the OAuth 2 web flow.

  1. User will click on a click to connect to the user’s Hubtel Unity account.

  2. Your app must redirect the user to Unity Portal to request authorization as follows.
    GET https://unity.hubtel.com/oauth.

Parameters

Name
Type
Description
Required

Client_is

string

The API Client ID for your app.

Yes

redirect_uri

string

The URL in your app where users will be sent after authorization.

scope

string

A space separated list of permissions. If not provided, scope defaults to an empty list of scopes for users that don’t have a valid token for the app. For users who do already have a valid token for the app, the user won’t be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the same scopes that were used last time the user completed the flow.

Yes

response_type

string

he type of response expected:

  • token: Use token for client or native applications
  • code: Use code for web or other secure applications

Yes

state

string

A user-defined string for identifying a particular request. It is sent back as part of the callback. It is useful in protecting against cross-site request forgery attacks. It is important that it is kept secret.

Yes

This should display the consent screen as shown below:

  1. The user will then grant access to your app by clicking accept on the consent screen.

  2. The user will be redirected to your app with the authorization code you can use to obtain an access token as follows:
    GET https://app.example.com/oauth_callback
    The URL above will be the same as the redirect URL in step 2 above.
    Parameter

Name
Type
Description

code

string

The authorization code you will use to get an access token.

state

string

The same state value you sent in step two above. You must ensure that the state values in both steps match.

  1. Your must then exchange the authorization code for an access token as follows:

POST https://unity.hubtel.com/oauth/token

Parameters

Name
Type
Description
Required

client_id

string

The API Client ID for your app.

Yes

client_secret

string

The API Client Secret for your app

code

string

The authorization code your app received in Step 4.

redirect_uri

string

The URL in your app where users will be sent after authorization.

grant_type

string

Indicates the type of token/code being used to get the access token. Options are:
authorization_code: Specified if you are using an authorization code to get an access token. It may only be used once.

refresh_token: Specified if you are using a refresh token to get an access_token. It may be used at any time to get an access token.

Response Type

access_token

string

The new access token

refresh_token

string

The new refresh token. Only partner applications will receive a refresh_token

expires_in

string

The access token expiry time in seconds

scope

string

The list of granted scopes

token_type

string

The type of token that has been supplied. typically, a bearer token.

The server will respond to the type of accept header you send by returning the appropriate format. By default the data is returned as application/x-www-form-urlencoded. The server will also return application/json and application/xml if those accept headers are sent.

  1. You can then use the access token to access the Unity API. The access token allows you application to make requests on behalf of the user.

You pass the access token into the request as an Authorization header with the bearer scheme as follows:
Authorization: Bearer <access_token>

  1. Your app must the handle the response from the API in the intended way.
Suggest Edits

Authorizing Client Apps (JavaScript or Native Apps) - OAuth 2.0 Client Application Flow

 

Mobile, Desktop, and JavaScript browser applications cannot guarantee the security of a common client secret, thus a different method must be used to ensure a secure exchange of data via the API.

  1. In this flow, the user will click on a click to connect to the user’s Hubtel Unity account. Your app must redirect the user to Unity Portal to request authorization as follows:
    GET https://unity.hubtel.com/oauth
    Parameter
Name
Type
Description
Required

client_id

string

The Client ID for your app.

Yes

redirect_uri

string

The URL in your app where users will be sent after authorization.

Yes

scope

string

A space separated list of permissions. If not provided, scope defaults to an empty list of scopes for users that don’t have a valid token for the app. For users who do already have a valid token for the app, the user won’t be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the same scopes that were used last time the user completed the flow.

Yes

response_type

string

The type of response expected:

  • token: Use token for client or native applications
  • code: Use code for web or other secure applications

Yes

state

string

A user-defined string for identifying a particular request. It is sent back as part of the callback. It is useful in protecting against cross-site request forgery attacks. It is important that it is kept secret.

Yes

This should display the consent screen as shown below:

  1. The user will then grant access to your app by clicking accept on the consent screen.

  2. Instead of the user being redirected to the call back URL, a redirect is returned containing the access token and other parameters in a URL fragment (example:http://myurl#access_token=<token>&state=<state>). Parameters being passed in a URL fragment means the parameters will not be passed on to any web server.

Name
Type
Description

access_token

string

The new access token

expires-in

string

The access token expiry time in seconds

scope

string

The list of granted scopes

token_type

string

The type of token that has been supplied. typically, a bearer token.

state

string

The same state parameter supplied in the authorization request

  1. You can then use the access token to access the Unity API. The access token allows you application to make requests on behalf of the user.
    You pass the access token into the request as an Authorization header with the bearer scheme as follows:

Authorisation: bearer <access_token>
Your app must handle the response from the API in the intended way.

Suggest Edits

Unity API OAuth Scopes

 

By authorizing your application, the user will typically have granted permission to your application to access resources within one or more scopes.

In order for your application to function correctly, the user must grant access to all your requested scopes. The user cannot grant you less than you requested.

There are certain cases where some scopes will implicitly require that other scopes are granted. In this case the required scopes will be automatically added for the user to review and consent when your app is requesting authorization.

Below is a list of scopes available on the Uniy API. This list may change when more resources become available on the API.

As you can see, scope names are formatted as object.action, where “object” refers to a Unity API data resource, and “action” indicates what can be done on the resource. A more detailed description of each action can be found in our Unity API Objects field guide.

Name
Description
Category

account.balance

know your balance

Account

account.details

Retrieve your account details

Account

account.invoices

Read all invoices associated with your account

Account

account.settings

Modify your account's preferences

Account

account.topup

Top-up your account

Account

campaigns.assignkeyword

Assign a keyword for a campaign

Campaign

campaigns.create

Create a new campaign

Campaign

campaigns.delete

Delete a campaign

Campaign

campaigns.edit

Edit a campaign

Campaign

campaigns.read

Read your campaign information

Campaign

campaigns.setdefaultemail

Set a default email forwarding address for a campaign

Campaign

campaigns.setdefaultreply

Set a URL source for a campaign

Campaign

campaigns.setforwardtomobile

Set a mobile number for a campaign

Campaign

campaigns.setforwardtosmpp

Set an SMPP address for a campaign

Campaign

contacts.create

Create a contact for your campaign

Contacts

contacts.delete

Delete your account's contact(s)

Contacts

contacts.edit

Modify your account's contact(s)

Contacts

contacts.read

Read your accounts contacts

Contacts

groups.create

Create a group on your behalf

Groups

groups.delete

Delete a group from your account

Groups

groups.edit

Edit your account groups

Groups

groups.read

Read your account groups

Groups

keywords.delete

Delete a keyword

Keywords

keywords.edit

Edit a keyword

Keywords

keywords.read

Read a keyword

Keywords

messages.read

Read your messaging history

Messages

messages.send

Send SMS from your account

Messages

msgtemplate.delete

Delete a message template from your account

Messages Templates

msgtemplate.create

Create a new message template

Messages Templates

msgtemplate.edit

Edit your message template(s)

Messages Templates

msgtemplate.read

Read your message template(s)

Messages Templates

numberplans.create

Create a number plan

Number Plans

numberplans.delete

Delete a number plan

Number Plans

numberplans.edit

Edit a number plan

Number Plans

numberplans.read

Read your number plans

Number Plans

offline_access

Access your account even when you are logged out of the system

Account

senderids.create

Create sender IDs on your behalf

Sender ID

senderids.delete

Delete one or more sender IDs in your account

Sender ID

senderids.edit

Edit a sender ID n your account

Sender ID

senderids.read

Read your sender IDs

Sender ID

Suggest Edits

Public Apps

Public applications can access resources on other Unity accounts. Public apps are useful for services that complement the features of Unity. Public apps use standard OAuth 2.0 authorization process to have access to Unity account resources. In general, if you have an application that will be using multiple applications, we recommend that you use OAuth 2.0.

 
Suggest Edits

Public App Properties

 
Name
Details

Public App

Check this option to indicate that the application is a public application, and will be using OAuth 2.0 for its authentication.

Display Name

This is the name of the app as you want users to see it.

callbackURL

Your application’s callback URL. This URL will be hit once the user has authorized your application. Find out more information on the OAuth Implementation Page.

Deauthorization callback

This URL will be fetched when the user removes authorization for your app. Find out more details on the OAuth Implementation Page.

Application Permission

The access requirements for your application. Find out more details on the OAuth Implementation Page here: http://developers.hubtel.com/documentations/unity/oauth.

Suggest Edits

Authentication

 

Applications that need to access resources on behalf of another user should use OAuth 2.0. HTTP basic authentication, and URL authentication would require the users of an application to provide their own Client ID and Client Secret combinations: most users would simply not be able to provide this information.
OAuth uses tokens to authorize an application on behalf of a user. It provides two main features:

• Restricted Access:
OAuth has been described a valet key for the web. A valet key allows the valet to drive a car, but the valet key cannot be used to open the trunk or glove compartment of the car. The same way, OAuth gives a client application access to restricted resources on a user’s account. For example an application can only be given access to read a user’s contacts, but not be able to alter the contacts. Providing a username and password, would however enable an app to fully impersonate a user account, and could lead to serious problems with security as well as requiring the application to be informed of every password change.

• Revocable Access:
A user can at any time remove the access given by an application. This can be done for each individual application without affecting other applications that the user has authorized.

OAuth 2.0 makes extensive use of the following tokens:

  1. Access Token – These tokens are valid for 30 days by default. After 30 days, an app must ask the user to

  2. Refresh Token - Public Apps do not receive refresh tokens. To receive a refresh token, you must publish your app as a partner application.
    The tokens must be kept secure and should not be shared under any circumstances.

Suggest Edits

Partner Application

 
Suggest Edits

Partner App Properties

Partner apps are public applications that have been published for display on the Unity Portal application directory.

Partner applications indicate more trust between Hubtel and the publisher of the application.

 
Name
Details

App Access URL

Your application’s access URL. If the app is a mobile app, this URL must point to the App Store link for your platform. If your app is multi-platform, then this URL can point to the landing page for selecting a platform.

category

A category for your app to help users find your app in the application directory.

short description

A brief description of your app. Typically a few sentences describing the key features of your app. Markdown formatting may be used here.

Long description

A more detailed description of your app. You may highlight all the features in your application. Markdown formatting may be used here.

Small Icon URL

A minimum 100 by 100 pixel icon for display in the Apps Grid Menu

Large Icon URL

A larger logo for your application. It must have a maximum height of 128 pixels.

Marketing URL

A wonderful URL for your app where you can fully convince the user to get your app. You may display screenshots, demo videos etc.

Terms of Service URL

Your application’s terms of service. This will be shown to users prior to them authorizing your app.

Privacy Policy URL

Your application’s privacy policy. This will be shown to users prior to them authorizing your app.

Publisher Name

Your company name, or your full name if you are publishing an app as an individual.

Publisher Website

Your website address.

Publisher Email Address

Your email address.

Publisher Address

Your physical address.

Publisher Logo URL

Your company logo.

Suggest Edits

Trusted Application

Applications published by Hubtel have special capabilities that can be enabled via our business center. Trusted apps have the following capabilities:

 

Default Installation
Trusted apps can be installed automatically for all users on any Hubtel organization.

Skip Consent
Trusted apps will not require consent when being installed by users. Indeed, trusted apps can be installed without user intervention.

Single-Sign on and Single-Sign out
Trusted apps can perform user-identity integration via OpenID Connect.

Roles
Trusted apps can publish roles for users on an organization.

Name
Details

Grant Client ID

Check this option to indicate that the application is a public application, and will be using OAuth 2.0 for its authentication.

Identify Client ID

This is the name of the app as you want users to see it.

CallbackURL

Your application’s callback URL. This URL will be hit once the user has authorized your application. Find out more information on the OAuth Implementation Page.

Authorization Callback URL

This URL will be fetched when the application is installed without user intervention. This is to enable the application set up some basic defaults before the user visits the application for the first time.

Switch Session URL

This URL will respond to redirects when a user changes organization while using an application. If this URL is not set, the user will be redirected to the Unity Portal.

Logout URL

This Logout URL will enable an application to be notified of a log out event, and thus remove the relevant cookies.

Suggest Edits

Private Apps

Private apps have access to only the owner’s Unity account. You can create an unlimited number of private applications on your account.

Private applications are useful if your application will only access resources on your Unity account. Private applications have access to all resources on your Unity account.

 
Suggest Edits

Authentication

 

Private apps are authenticated by the Client ID / Client Secret combination using:

• HTTP Basic Authentication:
You authenticate your request by using your client ID as username, and client secret as password.

• URL Authentication:
You authenticate by requesting the API endpoint with the ClientID=<#####> and ClientSecret=<#####> url parameters.