Subscription API

Subscription API

Imagine an application where the users have to be subscribed for a period of time for usage. For example, a news application where users will need updates as soon as you send them, for which the users will have to be subscribed, where this API comes into play. Subscription REST API allows a subscriber to register or unregister to or from an app, send subscription notification, query subscription status and query subscriber base size.

Method

POST

 

Subscriber Registration/ Un-registration

This service comprises of registration/ un-registration request and response.
The subscription request URL for subscriber registration and un-registration service is as follows:
Simulator:
http://localhost:7000/ subscription/send
Active production:
https://api.dialog.lk/ subscription/send

 

 

Request

Following is a sample request for registering a user.


{
  "applicationId": "APP_001807",
  "password": "cf2b9e361c13bc54b86d3c8180b0fd242",
  "version": "1.0",
  "action": "1",
  "subscriberId": "tel:94771234567"
}

 

Following is a sample request for un- registering a user.


{
  "applicationId": "APP_001807",
  "password": "cf2b9e361c13bc54b86d3c8180b0fd242",
  "version": "1.0",
  "action": "0",
  "subscriberId": "tel:94771234567"
}

 

Following are the request parameters of registration/un-registration.

 

Parameter Name Description Type Mandatory /Optional
applicationId
Application ID as given when provisioned
String
Mandatory
password
Password as given when provisioned
String
Mandatory
version
API version shall be numbered as 1.0, 2.0 etc
String
Optional
If not specified shall be validated against the latest version.
action
Whether the subscriber is toopt in or opt out
Enumerated
0 – Opt Out
1 – Opt In
Mandatory
subscriberId
Telephone number of the user to be subscribed.
tel – for MSISDN
eg: tel:94771234567
Note: tel might be a masked number depending on the application
String
Mandatory

 

Response

Following is a sample response for registering a user.


{
  "version": "1.0",
  "requestId": "1374746416574",
  "statusCode": "S1000",
  "statusDetail": "SUCCESS",
  "subscriptionStatus": "REGISTERED"
}

 

Following is a sample response for un-registering a user.


{
  "version": "1.0",
  "requestId": "1374746416574",
  "statusCode": "S1000",
  "statusDetail": "SUCCESS",
  "subscriptionStatus": "UNREGISTERED"
}

 

Following are the registration/un-registration response parameters.

 

Parameter Name Description Type Mandatory / Optional
version
API version shall be numbered as 1.0, 2.0 etc
String
Will be specified always
requestId
Request ID to uniquely identify the request within the SDP
String
Will be specified always
statusCode
The status code for the entire request
String
Will be specified always
statusDetail
The status detail for the entire request
String
Will be specified always
subscriptionStatus
Enum:
REGISTERED
UNREGISTERED
PENDING CHARGE – Subscriber is not charged yet.
Enum
Optional

 

 

Subscription Notification

This service comprises of Subscription Notification service’s notification and response.

 

NOTE: The subscription notification is received to the URL which is configured when provisioning.

 

Request

Following is a sample subscription notification.


{
  "applicationId": "APP_001807",
  "frequency": "Monthly",
  "status": "REGISTERED",
  "subscriberId": "tel:94771234567",
  "version": "1.0",
  "timeStamp": "20130402025896"
}

 

Following are the notification parameters of Subscription Notification service.

 

Parameter Name Description Type Mandatory / Optional
version
API version shall be numbered as 1.0, 2.0 etc
string
Will be specified
subscriberId
Subcribed users ID
subscriberID: tel:94771234567
If the application is masked then the number will be masked.
string
At least one will be specified
applicationId
Application ID as given when provisioned
string
Will be specified
frequency
Number of days the subscription is made for, till it is billed again.
Value specified in number of days – monthly subs will be specified as 30 days.
Integer
Will be specified
status
Status of the subscription
Enum
REGISTERED
UNREGISTERED
PENDING CHARGE
Will be specified
timeStamp
Time of subscription – yyyyMMddhhmmss
timestamp
Will be specified

 

 

Response

Following is a sample response for subscription notification.


{
  "statusCode": "S1000",
  "statusDetail": "Success"  
}

 

Following are the Subscription Notification Response parameters.

 

Parameter Name Description Type Mandatory / Optional
statusCode
The error code for the entire request
String
Mandatory
statusDetail
The error detail for the entire request
String
Mandatory

 

Query Subscription Status

This service comprises of Query Subscription Status service request and response. Notification URL for Query Subscription Status service is as follows:
Simulator:
http://localhost:7000/ subscription/getStatus
Active production:
https://api.dialog.lk/ subscription/getStatus

 

 

Request

Following is a sample request with mandatory parameters.


{
  "applicationId": "APP_001807",
  "password": "cf2b9e361c13bc54b86d3c8180b0fd242",
  "subscriberId": "te:94771234567"
}

 

Following are the request parameters of Query Subscription Status service.

 

Parameter Name Description Type Mandatory / Optional
applicationId
Application ID as given when provisioned.
string
Mandatory
password
Password as given when provisioned.
string
Mandatory
subscriberId
Address of the subscriber
Eg: tel:94771234567
Note: might be a masked number depending on the application
string
Mandatory

 

Response

Following is a sample response with Mandatory parameters.


{
  "version": "1.0",
  "subscriptionStatus": "REGISTERED",
  "statusCode": "S1000",
  "statusDetail": "SUCCESS"
}

 

Following are the Response parameters for Query Subscription Status service.

 

Parameter Name Description Type Mandatory / Optional
version
API version shall be numbered as 1.0, 2.0 etc
String
Mandatory
subscriptionStatus
REGISTERED
UNREGISTERED
PENDING CHARGE
String
Optional
statusCode
The error code for the entire request
String
Mandatory
statusDetail
The error detail for the entire request
String
Mandatory

 

Query Subscriber Base Size

This service comprises of Query Subscription Base Size, service request and response. Notification URL for service is as follows:
Simulator:
http://localhost:7000/ subscription/query-base
Active production:
https://api.dialog.lk/ subscription/query-base

 

Request

Following is a sample request with mandatory parameters.


{
  "applicationId": "APP_001807",
  "password": "cf2b9e361c13bc54b86d3c8180b0fd242"
}

 

Following are the request parameters of Query Subscription Status service.

 

Parameter Name Description Type Mandatory / Optional
applicationId
Application ID as given when provisioned
string
Mandatory
password
Password as given when provisioned
string
Mandatory

 

 

Response

Following is a sample response with Mandatory and optional parameters.


{
  "version": "1.0",
  "baseSize": "10",
  "statusCode": "S1000",
  "statusDetail": "SUCCESS"
}

Following are the Response parameters for Query Subscription Status service.

 

Parameter Name Description Type Mandatory / Optional
version
API version shall be numbered as 1.0, 2.0 etc
String
Mandatory
baseSize
The current subscribers base size
String
Optional
statusCode
The status code for the entire request
String
Mandatory
statusDetail
The status detail for the entire request
String
Mandatory