API reference

Subscription API

Handle the full subscription lifecycle. Register and unregister subscribers, check subscription status, push notifications, and monitor the size of your subscriber base, all from one API.

Base URL
https://api.applink.com.bd
Content type
application/json;charset=utf-8
Endpoints
4
POST

User Subscription

https://api.applink.com.bd/subscription/send

This service handles user subscription process(subscription/unsubscription)

Request body

application/json;charset=utf-8

applicationId
stringRequired
Used to identify the application. This is a unique identifier generated while provisioning an application. Only a single value can be sent per request.
ExampleAPP_999999
password
stringRequired
This API key will be sent to your registered email address on the platform upon application approval.
Example95904999aa8edb0c038b3295fdd271de
subscriberId
stringRequired
This can be the MSISDN of the subscriber to be charged. This is a unique identifier. tel: is for MSISDN Subcriber: tel:8801959979376 Note: tel might be a masked number depending on the type of the application Only a single value can be sent per request.
Exampletel:8801959979376
action
string enumRequired
0 -user unsubscription 1 -user subscription
Allowed01
Example0
curl -X POST https://api.applink.com.bd/subscription/send \
  -H "Content-Type: application/json;charset=utf-8" \
  -d '{
    "applicationId": "APP_999999",
    "password": "95904999aa8edb0c038b3295fdd271de",
    "subscriberId": "tel:8801959979376",
    "action": "0"
  }'

Response

version
stringRequired
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.
Example1.0
statusCode
stringRequired
Status code for the request. S = success, E = error, P = partial. See the status code table.
ExampleS1000
statusDetail
stringRequired
Human-readable description of the status. See the status code table.
Examplenot registered
subscriptionStatus
stringRequired
Status of the subscription eg:UNREGISTERED,REGISTERED
ExampleUNREGISTERED
JSON
{
  "version": "1.0",
  "statusCode": "S1000",
  "statusDetail": "not registered",
  "subscriptionStatus": "UNREGISTERED"
}
POST

Base Size

https://api.applink.com.bd/subscription/query-base

This service returns the number of registered subscribers

Request body

application/json;charset=utf-8

applicationId
stringRequired
Used to identify the application. This is a unique identifier generated while provisioning an application. Only a single value can be sent per request.
ExampleAPP_000201
password
stringRequired
This API key will be sent to your registered email address on the platform upon application approval.
Example39a8d1cb245029d0560619a2b388669c
curl -X POST https://api.applink.com.bd/subscription/query-base \
  -H "Content-Type: application/json;charset=utf-8" \
  -d '{
    "applicationId": "APP_000201",
    "password": "39a8d1cb245029d0560619a2b388669c"
  }'

Response

baseSize
stringRequired
Number of registered users
Example0
version
stringRequired
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.
Example1.0
statusCode
stringRequired
Status code for the request. S = success, E = error, P = partial. See the status code table.
ExampleS1000
statusDetail
stringRequired
Human-readable description of the status. See the status code table.
ExampleSuccess.
JSON
{
  "baseSize": "0",
  "version": "1.0",
  "statusCode": "S1000",
  "statusDetail": "Success."
}
POST

Get Subscriber Charging Info

https://api.applink.com.bd/subscription/getSubscriberChargingInfo

This service returns the current subscription status and last charging details for up to 10 subscribers in a single request.

Request body

application/json;charset=utf-8

applicationId
stringRequired
Used to identify the application. This is a unique identifier generated while provisioning an application. Only a single value can be sent per request.
ExampleAPP_102672
password
stringRequired
This API key will be sent to your registered email address on the platform upon application approval.
Examplecf2b9e361c13bc54b86d3c8180b0582fd
subscriberIds
stringOptional
MSISDNs of the list of subscribers. Eg: [tel: 8801973579363, tel:8801973579363] 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
Example['tel: 8801973579363', 'tel: 8801973579363']
curl -X POST https://api.applink.com.bd/subscription/getSubscriberChargingInfo \
  -H "Content-Type: application/json;charset=utf-8" \
  -d '{
    "applicationId": "APP_102672",
    "password": "cf2b9e361c13bc54b86d3c8180b0582fd",
    "subscriberIds": [
      "tel: 8801973579363",
      "tel: 8801973579363"
    ]
  }'

Response

version
stringRequired
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.
Example1.0
destinationResponses
arrayOptional
·
destinationResponses.subscriberId
stringRequired
MSISDN of the subscriber. If the application accepts masked numbers, list of masked numbers must be communicated in this parameter THIS IS A MANDATORY FILED
Exampletel:8801973579363
destinationResponses.subscriptionStatus
stringOptional
Status of the subscription Eg: INITIAL, REG_PENDING, TRIAL, REGISTERED, UNREGISTERED and TEMPORARY_BLOCKED
ExampleREGISTERED
destinationResponses.lastChargedDate
stringOptional
The successful last charged date of the subscriber in the format of YYYY-MM-DD hh:mm:ss
Example2020-01-23 22:03:22
destinationResponses.lastChargedAmount
stringOptional
The successful last charged amount for the subscriber with the currency code
Example30.00 BDT
destinationResponses.numberType
stringOptional
Denotes whether the subscriber is prepaid or postpaid
Examplepostpaid
destinationResponses.statusCode
stringOptional
Status code for the request. S = success, E = error, P = partial. See the status code table.
ExampleS1000
destinationResponses.statusDetail
stringOptional
Human-readable description of the status. See the status code table.
ExampleRequest was successfully processes
statusCode
stringRequired
Status code for the request. S = success, E = error, P = partial. See the status code table.
ExampleS1000
statusDetail
stringRequired
Human-readable description of the status. See the status code table.
ExampleSuccess.
JSON
{
  "version": "1.0",
  "destinationResponses": [
    {
      "subscriberId": "tel:8801973579363",
      "subscriptionStatus": "REGISTERED",
      "lastChargedDate": "2020-01-23 22:03:22",
      "lastChargedAmount": "30.00 BDT",
      "numberType": "postpaid",
      "statusCode": "S1000",
      "statusDetail": "Request was successfully processes"
    }
  ],
  "statusCode": "S1000",
  "statusDetail": "Success."
}
Status codes this endpoint returns8
Status codes for /subscription/getSubscriberChargingInfo
S1000Process completed successfully for all the available destination numbers.
E1303IP address from which this request originated is not provisioned to send request to application <application-id>. Please use a provisioned system to send request or contact system admin to provision the new IP.
E1312Request is invalid. <specify_the_reason> Refer the TAP NBL API Developer Guide for the mandatory fields and correct format of the request.
E1313Authentication failed. No such active application with applicationId <application-id>, or no active service provider or the given password in the request is invalid.
E1317<MSISDN> in request is invalid or not allowed.
E1325Format of the address is invalid. Expected format is tel:8801959979376.
E1601System experienced an unexpected error.
E1603Temporary system error occurred while delivering your request.
POST

Subscriber Notifications

https://api.applink.com.bd/subscription/notify

This service sends subscription notifications. Each notification identifies the subscriber (subscriberId), the frequency of the notifications and the subscription status, for example REGISTERED or UNREGISTERED.

Request body

application/json;charset=utf-8

timeStamp
stringRequired
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)
Example20120113082110
version
stringRequired
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.
Example1.0
applicationId
stringRequired
Used to identify the application. This is a unique identifier generated while provisioning an application. Only a single value can be sent per request.
ExampleAPP_999999
password
stringRequired
This API key will be sent to your registered email address on the platform upon application approval.
Example95904999aa8edb0c038b3295fdd271de
subscriberId
stringRequired
This can be the MSISDN of the subscriber to be charged. This is a unique identifier. tel: is for MSISDN Subcriber: tel:8801973579363 Note: tel might be a masked number depending on the type of the application Only a single value can be sent per request.
Exampletel:8801973579363
frequency
string enumRequired
Frequency of notifications being sent
Alloweddailyweeklymonthlyyearly
Examplemonthly
status
stringRequired
Status of the subscription eg:UNREGISTERED,REGISTERED
ExampleREGISTERED
curl -X POST https://api.applink.com.bd/subscription/notify \
  -H "Content-Type: application/json;charset=utf-8" \
  -d '{
    "timeStamp": "20120113082110",
    "version": "1.0",
    "applicationId": "APP_999999",
    "password": "95904999aa8edb0c038b3295fdd271de",
    "subscriberId": "tel:8801973579363",
    "frequency": "monthly",
    "status": "REGISTERED"
  }'

Response

statusCode
stringRequired
Status code for the request. S = success, E = error, P = partial. See the status code table.
ExampleS1000
statusDetail
stringRequired
Human-readable description of the status. See the status code table.
ExampleRequest was successfully processed
JSON
{
  "statusCode": "S1000",
  "statusDetail": "Request was successfully processed"
}

Subscription states

getSubscriberChargingInfo reports where each subscriber sits in the subscription lifecycle, and which fields come back in each state.

Subscription lifecycle states
INITIAL

Subscription request is sent to the system. The subscription request might not be completed, possibly due to a system error. Not even the charging call is made during this instance.

ReturnssubscriberIdsubscriptionStatusnumberTypestatusCodestatusDetail
REG_PENDING

Subscription request is made and the charging request is also sent, but charging is not yet successful (e.g. charging response not yet received from the IN, insufficient balance).

ReturnssubscriberIdsubscriptionStatusnumberTypestatusCodestatusDetail
TRIAL

Subscription request is made and the platform allows subscribers to use the service without charging, as they have a free trial period enabled.

ReturnssubscriberIdsubscriptionStatusnumberTypestatusCodestatusDetail
REGISTERED

Subscription request is made, charging is successful and the subscriber can receive the service. *

ReturnssubscriberIdsubscriptionStatuslastChargedDatelastChargedAmountnumberTypestatusCodestatusDetail
UNREGISTERED

Subscription request is made and unsubscription is also done by the subscriber for the particular service. *

ReturnssubscriberIdsubscriptionStatuslastChargedDatelastChargedAmountnumberTypestatusCodestatusDetail
TEMPORARY_BLOCKED

Subscription request is made, initial charging was successful and the subscriber was in the registered status once, but recursive charging has failed (e.g. due to insufficient balance) and the service is temporarily blocked for this subscriber. *

ReturnssubscriberIdsubscriptionStatuslastChargedDatelastChargedAmountnumberTypestatusCodestatusDetail

* If the application is a free application, lastChargedDate is omitted and lastChargedAmount is sent as 0.00 BDT.