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.
|
Following is a sample request for un- registering a user.
|
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 |
OptionalIf not specified shall be validated against the latest version. |
action |
Whether the subscriber is toopt in or opt out |
Enumerated0 – Opt Out1 – Opt In |
Mandatory |
subscriberId |
Telephone number of the user to be subscribed.tel – for MSISDNeg: tel:94771234567
|
String |
Mandatory |
Response
Following is a sample response for registering a user.
|
Following is a sample response for un-registering a user.
|
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:REGISTEREDUNREGISTEREDPENDING 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.
|
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 IDsubscriberID: tel:94771234567If 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
|
Will be specified |
timeStamp |
Time of subscription – yyyyMMddhhmmss |
timestamp |
Will be specified |
Response
Following is a sample response for subscription notification.
|
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.
|
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 subscriberEg: tel:94771234567Note: might be a masked number depending on the application |
string |
Mandatory |
Response
Following is a sample response with Mandatory parameters.
|
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 |
REGISTEREDUNREGISTEREDPENDING 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.
|
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.
|
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 |