logo
Documentation Powered by ReDoc

TadHack2021 API Documentation (1.0)

Download OpenAPI specification:Download

sms/send

This service allows the user to send SMS to one or more terminals (phones or any SMS-enabled device) from their application.

SMS send service supports only POST HTTP requests. This is used when sending SMS to a mobile phone from an application.

An application wishing to initiate an MT SMS message should use this operation type.

SMS Mobile Termination

Request Body schema: application/json;charset=utf-8
version
required
string

API version shall be numbered as 1.0, 2.0 etc.

If version is specified in the request, same version must be sent in the response.

If version is not specified in the request, the latest version will be specified in the response.

applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.

password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.

message
required
string

Content of the message that needs to be sent.

Messages over the limit shall be broken up by the platform before sending

destinationAddresses
required
Array of strings

List of destination addresses should be telephone numbers.(tel - for MSISDN).

tel:94776177301.

Address can also have the value - tel: all

which will in return be a message to the subscribed base of the application

at least one should be specified

Note : tel might be a masked number depending on the type of application

sourceAddress
string

Address of the source.

sourceAddress: tel:94776177301

at least one will be specified

deliveryStatusRequest
string
Enum: 0 1

Indicates the need of a Delivery Status Report for the message.

0 - Delivery Report not required

1 - Delivery Report Required

encoding
string
Enum: 0 240 245

Encoding scheme used in the message

If not specified taken as Text

If the encoding type is “Binary” then the message content will be represented as hex encoded.

0 - Text

240 - Flash SMS

245 - Binary SMS

binaryHeader
string <hexadecimal>

For advanced type of messages where the binary header shall be sent from the application

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0",
  • "applicationId": "APP_999999",
  • "password": "password",
  • "message": "Hello",
  • "destinationAddresses": [
    ],
  • "sourceAddress": "77000",
  • "deliveryStatusRequest": "1",
  • "encoding": "245",
  • "binaryHeader": "526574697265206170706c69636174696f6e20616e642072656c6561736520524b7320696620666f756e642065787069726564"
}

Response samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0",
  • "requestId": "101901031657410007",
  • "destinationResponses": [
    ],
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

sms/receive

This service retrieves the SMS sent to the web application. Receive service returns only a list of SMS messages received since the previous invocation of the method.

SMS Mobile Origination

Request Body schema: application/json;charset=utf-8
version
required
string

API version shall be numbered as 1.0, 2.0 etc.

If version is specified in the request, same version must be sent in the response.

If version is not specified in the request, the latest version will be specified in the response.

applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.

sourceAddress
required
string

Address of the source.

sourceAddress: tel:94776177301

at least one will be specified

message
required
string

Content of the message sent by the user

requestId
required
string

Uniquely identifies a request within TAP

encoding
required
string
Enum: 0 240 245

Encoding scheme used in the message.

If the encoding type is “Binary” then the message content will be represented as hex encoded.

0 - Text

240 - Flash SMS

245 - Binary SMS

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0",
  • "applicationId": "APP_000029",
  • "sourceAddress": "tel:94776177301",
  • "message": "string",
  • "requestId": "APP_000001",
  • "encoding": "0"
}

Response samples

Content type
application/json;charset=utf-8
{
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

sms/report

When performing a SendSms Operation if an application has requested for a Delivery Response message from the Message Centre, then TAP will initiate the Delivery Report service to hand over the Delivery Response message to the application. The messageId should be used to match the MT response with the Delivery Report.

Delivery Status Report Service

Request Body schema: application/json;charset=utf-8
destinationAddress
required
string

Address of the subscriber

timeStamp
required
string

The timestamp sent from the SMS

"yyMMddHHmm"

yy – last two digits of the year (00-99)

MM – month (01-12)

dd – day (01-31)

HH – hour (00-23)

mm- minute (00-59)

requestId
required
string

Uniquely identifies a request within TAP

deliveryStatus
required
string
Enum: "DELIVERED" "EXPIRED" "DELETED" "UNDELIVERABLE" "ACCEPTED" "UNKNOWN" "REJECTED"

Enum from TAP to Application:

DELIVERED ,EXPIRED ,DELETED ,UNDELIVERABLE ,ACCEPTED ,UNKNOWN ,REJECTED

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "destinationAddress": "tel:94776177301",
  • "timeStamp": "20120113082110",
  • "requestId": "MSG_000111",
  • "deliveryStatus": "DELIVERED"
}

Response samples

Content type
application/json;charset=utf-8
{
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

ussd/send

This service is used when sending USSD messages to a mobile phone from an application.USSD send service supports only POST HTTP requests.

Ussd Send Services

Request Body schema: application/json;charset=utf-8
version
required
string

API version shall be numbered as 1.0, 2.0 etc.

If version is specified in the request, same version must be sent in the response.

If version is not specified in the request, the latest version will be specified in the response.

applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.

message
required
string

Content of the message sent by the application

password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.

sessionId
required
string

Unique number that USSD Gateway assigns to the application for the duration of the session. This number will be maintained in all the messages throughout a single session.

ussdOperation
required
string
Enum: "mo-init" "mo-cont" "mt-init" "mt-cont" "mt-fin"

USSD operation

mo-cont:TAP to assign for and USSD message originated from subscriber, that comes after a init

nmt-init: App to assign when a USSD session is initiated by an application

mt-cont: App to assign for any USSD message originated from application, that comes after a init

mt-fin: App to assign when session ends in final message

Data type will be string where the operation name itself will be used in the parameter value.

destinationAddress
required
string

Destination address should be a telephone number (tel - for MSISDN)

Note : tel might be a masked number depending on the type of application

encoding
string
Value: 440

Encoding scheme used in the message

440 - Plain ASCII characters

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0",
  • "applicationId": "APP_000001",
  • "message": "1. Press One\n 2. Press two\n 3. Press three\n 4. Exit\n",
  • "password": "password",
  • "sessionId": "1330929317043",
  • "ussdOperation": "mt-cont",
  • "destinationAddress": "tel:94776177301 ",
  • "encoding": "440"
}

Response samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0",
  • "requestId": "101901031657410007",
  • "timeStamp": "20190103165801",
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

ussd/receive

This service allows TAP to deliver MO messages to the application using HTTP – based API. The flow of messages is initiated by a MO request sent to an application,TAP will deliver the message to the application as an acknowledgement. Hence it could be either request-response exchange or a request-exception exchange.

Receive USSD request is a MO message which will be sent to the application through hSenid Mobile APIs as a delivery request.

Ussd Receive Services

Request Body schema: application/json;charset=utf-8
version
required
string

API version shall be numbered as 1.0, 2.0 etc.

If version is specified in the request, same version must be sent in the response.

If version is not specified in the request, the latest version will be specified in the response.

applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.

message
required
string

Content of the message sent by the user

requestId
required
string

Uniquely identifies a request within TAP

sessionId
required
string

Unique number that USSD Gateway assigns to the application for the duration of the session. This number will be maintained in all the messages throughout a single session.

ussdOperation
required
string
Enum: "mo-init" "mo-cont" "mt-init" "mt-cont" "mt-fin"

USSD operation

mo-cont:TAP to assign for and USSD message originated from subscriber, that comes after a init

mt-init: App to assign when a USSD session is initiated by an application

mt-cont: App to assign for any USSD message originated from application, that comes after a init

mt-fin: App to assign when session ends in final message

sourceAddress
required
string

Address of the source.

sourceAddress:tel:94776177301

at least one will be specified

vlrAddress
string

VLR(Visitor Location Register) address of the sender

encoding
required
string
Value: 440

Encoding scheme used in the message

440 - Plain ASCII characters

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0",
  • "applicationId": "APP_000029",
  • "message": "*141#",
  • "requestId": "1330933229901",
  • "sessionId": "1330929317043",
  • "ussdOperation": "mt-cont",
  • "sourceAddress": "tel:94776177301",
  • "vlrAddress": "tel:94776177301",
  • "encoding": "440"
}

Response samples

Content type
application/json;charset=utf-8
{
  • "statusCode": "S1000",
  • "statusDetail": "Success"
}

caas/directDebit

This service charges a specific amount from a subscriber’s account.

Direct Debit

Request Body schema: application/json;charset=utf-8
applicationId
required
string

Used to identify the application. This is a unique identifier generated by the system when provisioning an application.

Only a single value can be sent per request.

password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.

externalTrxId
required
string

This is the transaction ID generated by the application to map the request with the response.

This is needed to avoid any conflicts when SP inquires about a transaction.

Only a single value can be sent per request.

subscriberId
required
string

This can be the MSISDN of the subscriber to be charged. This is a unique identifier.

tel:94776177301 is for MSISDN

Subcriber: tel:94776177301

Note: tel might be a masked number depending on the type of the application

Only a single value can be sent per request.

paymentInstrumentName
required
string
Value: "Mobile Account"

The name of the payment instrument.

Only a single value can be sent per request.

accountId
string

The account of the payment instrument.

Only a single value can be sent per request.

amount
required
string

Amount to be reserved for charging.

Only a single value can be sent per request.

currency
string

Currency unit of the amount.

Only a single value can be sent per request.

Only ‘LKR’ is allowed.

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "applicationId": "APP_999999",
  • "password": "95904999aa8edb0c038b3295fdd271de",
  • "externalTrxId": "12345678901234567890123456789012",
  • "subscriberId": "tel:94776177301",
  • "paymentInstrumentName": "Mobile Account",
  • "accountId": "12345",
  • "amount": "12345",
  • "currency": "LKR"
}

Response samples

Content type
application/json;charset=utf-8
{
  • "externalTrxId": "12345678901234567890123456789012",
  • "internalTrxId": "321",
  • "referenceId": "12345678",
  • "timeStamp": "2012-07-30T12:48:10-0400",
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

subscription/userSubscription

This service handles user subscription process(subscription/unsubscription)

User Subscription

Request Body schema: application/json;charset=utf-8
applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.

password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.

subscriberId
required
string

This can be the MSISDN of the subscriber to be charged. This is a unique identifier.

tel: is for MSISDN

Subcriber: tel:94776177301

Note: tel might be a masked number depending on the type of the application

Only a single value can be sent per request.

action
required
string
Enum: 0 1

0 -user unsubscription

1 -user subscription

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "applicationId": "APP_999999",
  • "password": "95904999aa8edb0c038b3295fdd271de",
  • "subscriberId": "tel:94776177301",
  • "action": "0"
}

Response samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0.",
  • "statusCode": "S1000",
  • "statusDetail": "not registered",
  • "subscriptionStatus": "UNREGISTERED."
}

subscription/baseSize

This service returns the number of registered subscribers

Base Size

Request Body schema: application/json;charset=utf-8
applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.

password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "applicationId": "APP_000201",
  • "password": "39a8d1cb245029d0560619a2b388669c"
}

Response samples

Content type
application/json;charset=utf-8
{
  • "baseSize": "0",
  • "version": "1.0.",
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

subscription/subscriberStatus

This service returns the user subscription status(unregistered,registered)

Subscriber Status

Request Body schema: application/json;charset=utf-8
applicationId
required
string

Unique identification of the application within the platform

password
required
string

Password given when provisioning the application

subscriberId
required
string

This is the MSISDN of the subscriber to be charged

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "applicationId": "APP_999999",
  • "password": "95904999aa8edb0c038b3295fdd271de",
  • "subscriberId": "tel:94776177301"
}

Response samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0.",
  • "statusCode": "S1000",
  • "statusDetail": "Request was successfully processed",
  • "subscriptionStatus": "UNREGISTERED."
}

subscription/getSubscriberChargingInfo

Get Subscriber Charging Info

Request Body schema: application/json;charset=utf-8
applicationId
required
string

Unique identification of the application within the platform

password
required
string

Password given when provisioning the application

subscriberIds
string

MSISDNs of the list of subscribers. Eg: [tel: 94772342345, tel: 94772678845, tel:9477982563]

If the application accepts masked numbers, list of

masked numbers must be communicated in this parameter

List can contain maximum of 10 MSISDNs per request

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "applicationId": "APP_102672",
  • "password": "cf2b9e361c13bc54b86d3c8180b0582fd",
  • "subscriberIds": [
    ]
}

Response samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0",
  • "destinationResponses": [
    ],
  • "statusCode": "S1000",
  • "statusDetail": "Success."
}

subscription/notify

This service sends notifications to the users

Subscriber Notifications

Request Body schema: application/json;charset=utf-8
timeStamp
required
string

The timestamp sent from the SMS. "yyMMddHHmm" yy – last two digits of the year (00-99) MM – month (01-12) dd – day (01-31) HH – hour (00-23) mm- minute (00-59)

version
required
string

API version shall be numbered as 1.0, 2.0 etc.

If version is specified in the request, same version must be sent in the response.

If version is not specified in the request, the latest version will be specified in the response.

applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.

password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.

subscriberId
required
string

This can be the MSISDN of the subscriber to be charged. This is a unique identifier.

tel:94776177301 is for MSISDN

Subcriber: tel:94776177301

Note: tel might be a masked number depending on the type of the application

Only a single value can be sent per request.

frequency
required
string
Enum: "daily" "weekly" "monthly" "yearly"

Frequency of notifications being sent

status
required
string

Status of the subscription eg:UNREGISTERED,REGISTERED

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "timeStamp": "20120113082110",
  • "version": "1.0",
  • "applicationId": "APP_999999",
  • "password": "95904999aa8edb0c038b3295fdd271de",
  • "subscriberId": "tel:94776177301",
  • "frequency": "monthly",
  • "status": "REGISTERED."
}

Response samples

Content type
application/json;charset=utf-8
{
  • "statusCode": "S1000",
  • "statusDetail": "Request was successfully processed"
}

otp/request

This service is used by the developer to request an OTP for a subscriber's MSISDN. Upon the request, hSenidMobile APIS will generate and send an OTP to the subscriber's MSISDN. This OTP must be entered by the subscriber into the mobile/web application to activate a subscription.

Request OTP

Request Body schema: application/json;charset=utf-8
applicationId
required
string

ID of the application

password
required
string

Password/API key given to uniquely identify the application

subscriberId
required
string

Mobile number of the end consumer

applicationHash
string

Hash string to determine which verification messages to send to your app.

object (applicationMetaData)

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "applicationId": "APP_000375",
  • "password": "a07118cda5215fc6d01db5b2ab848edd",
  • "subscriberId": "tel:94776177301",
  • "applicationHash": "abcdefgh",
  • "applicationMetaData": {}
}

Response samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0",
  • "statusCode": "S1000",
  • "referenceNo": "213561321321613",
  • "statusDetail": "Success"
}

otp/verify

This service is used by the developer to verify an OTP entered by a subscriber into the application. Upon a successful verification the subscription process of hSenidMobile APIs will be activated.

Verify OTP

Request Body schema: application/json;charset=utf-8
applicationId
required
string

ID of the application

password
required
string

Password/API key given to uniquely identify the application

referenceNo
required
string

Reference number returned with request OTP API

otp
required
string

One time password (OTP) to be used to MSISDN verification for the application

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "applicationId": "APP_000375",
  • "password": "a07118cda5215fc6d01db5b2ab848edd",
  • "referenceNo": "213561321321613",
  • "otp": "123564"
}

Response samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0",
  • "statusCode": "S1000",
  • "subscriptionStatus": "REGISTERED",
  • "statusDetail": "Success",
  • "subscriberId": "tel:sdfasdfasdfwqerqwtgfgsafgasfgasdfasdfasdfasdfasdfasf"
}

lbs/locate

This service allows to send and receive location requests using a REST based API to find the location of users and create rich & real-time applications. The Request Service of this API enables the Service Provider application to request location of a particular mobile number and receive the location as a response.

Get Location

This service allows to send and receive location requests using a REST based API to find the location of users and create rich & real-time applications. The Request Service of this API enables the Service Provider application to request location of a particular mobile number and receive the location as a response.

Request Body schema: application/json;charset=utf-8
version
required
string

API version shall be numbered as 1.0, 2.0 etc.

If version is specified in the request, same version must be sent in the response.

If version is not specified in the request, the latest version will be specified in the response.

applicationId
required
string

Used to identify the application. This is a unique identifier generated while provisioning an application.

Only a single value can be sent per request.

password
required
string

Used to authenticate the application originated message against the credentials of the service provider.

Encoded, single value.

subscriberId
required
string

MSISDN of the subscriber for which the location update is needed. This is a unique identifier.

serviceType
required
ENUM

Required MLP service type. Currently supports; IMMEDIATE

responseType
ENUM

QoS parameter defines the accepted delay for the response.Accepted values and precedence is as below; 1. NO_DELAY 2. LOW_DELAY 3. DELAY_TOLERANCE NO_DELAY has the highest precedence. Eg: Third party application can not initiate location requests with NO_DELAY if the provisioned value is ‘LOW DELAY’. But can initiate location requests with LOW_DELAY and DELAY_TOLERENCE.

horizontalAccuracy
ENUM

QoS parameter defines the required horizontal accuracy for the location update.Accepted values and their precedence is as follows; 1. 100 2. 500 3. 1000 4. 1500 Minimum value 100 has the highest precedence. Eg; Third party application can not initiate location requests with ‘100’ or ‘500’ if the provisioned value is ‘1000’. But can initiate location requests with ‘1000’ and ‘1500’.

freshness
ENUM

QoS parameter defines the required freshness for the location update.Accepted values and their precedence is as follows; 1. HIGH_LOW 2. LOW_HIGH 3. HIGH 4. LOW HIGH_LOW has the highest precedence. Eg; Third party application can not initiate location requests with ‘HIGH_LOW’ if the provisioned value is ‘LOW_HIGH’. But can initiate location requests with ‘LOW_HIGH’, ‘HIGH’ and ‘LOW’.

Responses

Request samples

Content type
application/json;charset=utf-8
{
  • "version": "1.0",
  • "applicationId": "APP_000029",
  • "password": "95904999aa8edb0c038b3295fdd271de",
  • "subscriberId": "1.0",
  • "serviceType": "IMMEDIATE",
  • "responseType": "NO_DELAY",
  • "horizontalAccuracy": "100",
  • "freshness": "HIGH"
}

Response samples

Content type
application/json;charset=utf-8
{
  • "statusCode": "S1000",
  • "statusDetail": "Success",
  • "timeStamp": "2012-07-30T12:48:10-0400",
  • "version": "1.0",
  • "messageID": "101901031657410007",
  • "latitude": "",
  • "longitude": "",
  • "freshness": "",
  • "horizontalAccuracy": 1,
  • "subscriberState": true
}

ivr/responseOfSimpleIVRMenuServices

This service allows to send and receive location requests using a REST based API to find the location of users and create rich & real-time applications. The Request Service of this API enables the Service Provider application to request location of a particular mobile number and receive the location as a response.

Interactive Voice Response

IVR (Interactive Voice Response) uses pre-recorded voice prompts and menus to provide information and options in order to receive responses from the users via keypad dialling. IVR applications are programs that control and respond to calls on the IVR platform. In creating an IVR application, developer needs to upload the audio files which need to be played and the JSON response formats which are required to manage the audio files to the hosting server. Once a user dials an IVR number, the call is received by the platform. Then the platform routes the call to the relevant application and sends the response to the call listener. A developer can create two types of IVR menus. Single Audio Response: When a user calls the IVR number only a single audio file is played. Simple IVR Menu: When a user calls the IVR number he/she first listens to a generic message that provides a list of options, requiring an input. Then based on the input of the caller the next audio is played. This sequence can be continued until the required closure is obtained, when the caller receives the desired outcome and terminates the call.

Responses

Request samples 

coming soon

Response samples

Content type
application/json;charset=utf-8
{
  • "name": "name",
  • "header": "string",
  • "audio": "string",
  • "menu": "string"
}

ivr/responseOfSingleAudioServices

Interactive Voice Response

IVR (Interactive Voice Response) uses pre-recorded voice prompts and menus to provide information and options in order to receive responses from the users via keypad dialling. IVR applications are programs that control and respond to calls on the IVR platform. In creating an IVR application, developer needs to upload the audio files which need to be played and the JSON response formats which are required to manage the audio files to the hosting server. Once a user dials an IVR number, the call is received by the platform. Then the platform routes the call to the relevant application and sends the response to the call listener. A developer can create two types of IVR menus. Single Audio Response: When a user calls the IVR number only a single audio file is played. Simple IVR Menu: When a user calls the IVR number he/she first listens to a generic message that provides a list of options, requiring an input. Then based on the input of the caller the next audio is played. This sequence can be continued until the required closure is obtained, when the caller receives the desired outcome and terminates the call.

Responses

Request samples 

coming soon

Response samples

Content type
application/json;charset=utf-8
{
  • "name": "hello",
  • "audio": "audio",
  • "refresh": "true"
}