Description

Public
Date Page
2020-07-07 1 (6)
Creator Approved by Identifier Revision Status
PnSDM Ncell-ICT-2018-AP10 1.0 Final

Contents
1. Introduction .......................................................................................................................................... 2
2. Security ................................................................................................................................................. 2
3. API Specification ................................................................................................................................... 2
3.1. General ......................................................................................................................................... 2
3.2. SMS ............................................................................................................................................... 2
3.2.1. Send SMS .............................................................................................................................. 2
3.2.2. Response Codes and Exceptions .......................................................................................... 5
4. Version History ..................................................................................................................................... 6

Company Information
Ncell Private Limited
 Description
Public
Date Page
2020-07-07 2 (6)
Creator Approved by Identifier Revision Status
PnSDM Ncell-ICT-2018-AP10 1.0 Final

1. Introduction
Ncell API Gateway exposes SMS capabilities for service provider.

All APIs defined in this document are accessible via RESTful web services. A RESTful service utilizes HTTP
commands POST, GET, PUT, and DELETE in order to perform an operation on a resource at the server. This
resource is addressed by a URL; and what is returned by the server is a representation of that resource
depending on its current state.

These are oneAPI v3 compliant and are JSON based RESTful APIs.

2. Security
It is recommended that the communication between the Ncell API Gateway and the service provider
should be via a secure channel (HTTPS) and over IPSec VPN.

Adherence to the URL patterns and response codes defined herein is mandatory.

3. API Specification
3.1. General
Ncell API gateway uses oAuth2 password grant type or authorization [Refer to Ncell-ICT-2018-AP01
Ncell_APG_Token_Specification.pdf ]. The access token obtained from authorization should be passed as bearer in
header for each API call.

3.2. SMS
Following functionalities are supported for SMS.

 Send an SMS from Application (MT)

3.2.1. Send SMS

HTTP Method POST
Operation Used to send an SMS from Application (to one or more mobile terminals).

3.2.1.1. Request Parameters

Parameter
Description Usage
name
At least one address will be provided; in this case the recipients
address MSISDN including the „tel:‟ protocol identifier and the country Mandatory
code .i.e., tel:97798XXXXXXXX.

Company Information
Ncell Private Limited
 Description
Public
Date Page
2020-07-07 3 (6)
Creator Approved by Identifier Revision Status
PnSDM Ncell-ICT-2018-AP10 1.0 Final
(string) will be passed back in this notification. It’s used to
identify the message the receipt relates to (or any other useful
callbackData data, such as a function name). This is only valid if notifications Optional
are required – sent with the notifyURL parameter within the
receiptRequest element

Mandatory
Keep Unique clientCorrelator to each SMS send so that client
clientCorrelator
can track based on it.

(string) will be provided within the outboundSMSTextMessage

message element. Messages over 160 characters will be sent as two or Mandatory
more messages.

Reserved for
notifyURL N/A
future

(string) is the address to whom a responding SMS may be sent.

senderAddress Mandatory
Required for P2A only. N/A now.
(string) is the URL-escaped name of the sender to appear on
senderName the terminal is the address to whom a responding SMS may be Mandatory
sent. This needs to be approved and white-listed in SMSC.

3.2.1.2. Request Sample

POST /apicall/smsmessaging/v2/outbound/ tel%3A%2B97798XXXXXXXX/requests
HTTP/1.1
Host: apg.ncell.axiata.com
Content-Type: application/json
Authorization: Bearer <<access key>>
Accept: application/json

{
"outboundSMSMessageRequest": {
"address": ["tel:<<97798XXXXXXXX>>"],
"senderAddress": "tel:<<XXXX>>",
"outboundSMSTextMessage": {
"message": "<<MESSAGE THAT NEEDS TO SEND>>"

},
"clientCorrelator": "<<Keep unique id>>",
"receiptRequest": {
"notifyURL": "<<NOTIFY URL>>”,
"callbackData": "<<MISC DATA>>"
},
"senderName": "<<NCELL APPROVED SENDER NAME>>"

Company Information
Ncell Private Limited
 Description
Public
Date Page
2020-07-07 4 (6)
Creator Approved by Identifier Revision Status
PnSDM Ncell-ICT-2018-AP10 1.0 Final
}
}
3.2.1.3. Response Parameters
The response should include all original request parameters as listed in the request.

For convenience, this URI is also included in the response body as the resourceURL pair within the
resourceReference object.

3.2.1.4. Response Sample

HTTP/1.1 200
Content-Type: application/json
Date: Thu, 04 Jun 2009 02:51:59 GMT

{
"outboundSMSMessageRequest": {
"address": [
"tel:+9779802100376"
],
"deliveryInfoList": {
"deliveryInfo": [
{
"address": "tel:+9779802100376",
"deliveryStatus": "MessageWaiting"
}
],
"resourceURL": "https://apg.ncell.axiata.com/apicall/smsmessaging/v2/outbound/tel%3ANcell
Bot/requests/6099793433950301/deliveryInfos"
},
"senderAddress": "tel:Ncell Bot",
"outboundSMSTextMessage": {
"message": "outbound"
},
"clientCorrelator": "testagain1231bh663",
"receiptRequest": {
"notifyURL": "http://10.70.12.162/notifyTest/notify.php",
"callbackData": "work"
},
"senderName": "Ncell Bot",
"resourceURL": "https://apg.ncell.axiata.com/apicall/smsmessaging/v2/outbound/tel%3ANcell
Bot/requests/6099793433950301"
}
}

NOTE: The HTTP 200 response shows API is successful.

Company Information
Ncell Private Limited
 Description
Public
Date Page
2020-07-07 5 (6)
Creator Approved by Identifier Revision Status
PnSDM Ncell-ICT-2018-AP10 1.0 Final
3.2.2. Response Codes and Exceptions
3.2.2.1. RESPONSE CODES
HTTP response codes are used to indicate:
200 – Success!
400 – Bad request; check the error message for details
401 – Authentication failure, check authentication details
403 – Forbidden; please provide authentication credentials
404 – Not found: mistake in the host or path of the service URI
405 – Method not allowed: for example you mistakenly used a HTTP GET instead of a POST
500 – The server encountered an unexpected condition. This could be wrong authentication
details or limited user permission
503 – Server busy and service unavailable. Please retry the request.

3.2.2.2. EXCEPTIONS
This section lists the available error codes, the possible reasons why the exception may have occurred,
and possible solutions.

3.2.2.2.1. SERVICE EXCEPTIONS

If the transaction is immediately confirmed, the response is displayed as follows,
HTTP/1.1
400 Bad Request
Accept: application/json

{
"requestError": {
"serviceException": {
"messageId": "SVC0002",
"text": " Invalid input value for message part %1",
"variables": " clientCorrelator Value 12345"
}
}
}

3.2.2.2.2. POLICY EXCEPTIONS

A policy exception means that the request syntax is valid, however an operator policy has been broken.

POL0001 - Policy error occurred

The above exception may be thrown to indicate a fault relating to a policy associated with the service.

Company Information
Ncell Private Limited
 Description
Public
Date Page
2020-07-07 6 (6)
Creator Approved by Identifier Revision Status
PnSDM Ncell-ICT-2018-AP10 1.0 Final

4. Version History
Version Date Changes Updater
1.0 07-07-2020 Initial PnSDM

Company Information
Ncell Private Limited