Subscription API


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