Subscription Manager

Content

Overview

The Subscription Manager API allows applications to create their own subscriptions. However prior to being allowed access to the API, certain configurations need to be made. In order to make these configurations a callback URL is necessary in order to notify when the status of the subscription changes.

Requirements

Subscription Manager Configurations
The following parameters are required in order to create a subscription manager record:

Parameter Name

Description

Type

Mandatory /Optional

callbackURL

The subscription name, it should be unique per application(i.e One application cannot contain two subscriptions of the name "Subscription", the API will reject this request).

string

Mandatory

SMS Port

This is the Port number configured for you, by the ideabiz Support team.

string

Mandatory, if you require SMS subscriptions

USSD Port

The USSD Port number configured for you, by the ideabiz Support team.

string

Mandatory, if you require USSD subscriptions

Authorization API Calls
All API call requests to ideabiz.lk require Authorization headers. Please refer the Token Management (http://docs.ideabiz.lk/Getting_Started/Token_Manegment) document for Authorization.

Request Header

Content-Type: application/json 
Authorization: Bearer [access token] 
Accept: application/json

Sample Request Header

Content-Type: application/json 
Authorization: Bearer a92ba8hjgjhgjh3fa1609cabcd79
Accept: application/json

Sending the subscription request

This allows you to send an subscription request from your Web application.

Request

Given below is a sample request:

URL

https://ideabiz.lk/apicall/submn/v1.0/new

Sample

https://ideabiz.lk/apicall/submn/v1.0/new

Method

POST

Body

{
  "subscriptionName": "New Subscription",
  "subscriptionDescription": "Subscription description",
  "regSms": "You've been successfully subscribed to New Subscription", 
  "unregSms": "You have successfully unsubscribed from New Subscription",
  "senderName": "IdeabizLK",
  "subscriptionUrl": "https://apps.ideabiz.lk/notify", 
  "operator": "Dialog",
  "apiVersion": "V3",
  "defaultConfig": true,
  "comment": "comment" 
}

Request for SMS (Subscription SMS)

Given below is a sample request:

URL

https://ideabiz.lk/apicall/submn/v1.0/new

Sample

https://ideabiz.lk/apicall/submn/v1.0/new

Method

POST

Body

{
  "subscriptionName": "New Subscription",
  "subscriptionDescription": "Subscription description",
  "regSms": "You've been successfully subscribed to New Subscription", 
  "unregSms": "You have successfully unsubscribed from New Subscription",
  "senderName": "IdeabizLK",
  "subscriptionUrl": "https://apps.ideabiz.lk/notify", 
  "operator": "Dialog",
  "apiVersion": "V3",
  "defaultConfig": true,
  "comment": "comment",
  "subscriptionSms":{
    "smsRegCode": "REG APP",
    "smsUnregCode": "UNREG APP",
    "smsNotifyUrl": "https://apps.ideabiz.lk/notify",
    "keyword": "HEY",
    "operator":"Dialog"
  } 
}

Request for USSD (Subscription USSD)

Given below is a sample request:

URL

https://ideabiz.lk/apicall/submn/v1.0/new

Sample

https://ideabiz.lk/apicall/submn/v1.0/new

Method

POST

Body

{
  "subscriptionName": "New Subscription",
  "subscriptionDescription": "Subscription description",
  "regSms": "You've been successfully subscribed to New Subscription", 
  "unregSms": "You have successfully unsubscribed from New Subscription",
  "senderName": "IdeabizLK",
  "subscriptionUrl": "https://apps.ideabiz.lk/notify", 
  "operator": "Dialog",
  "apiVersion": "V3",
  "defaultConfig": true,
  "comment": "comment",
  "subscriptionUssd":{
    "ussdRegKeyword":  456 ,
    "ussdUnregKeyword": 123,
    "ussdWelcomeMsg":  "Welcome!",
    "ussdUnregMsg": "Thank you for using the service!",
    "operator":"Dialog",
    "ussdNotifyUrl": "https://apps.ideabiz.lk/notify"
  }
}

Request for Charging (Payment V4)

Given below is a sample request:

URL

https://ideabiz.lk/apicall/submn/v1.0/new

Sample

https://ideabiz.lk/apicall/submn/v1.0/new

Method

POST

Body

{
  "subscriptionName": "New Subscription",
  "subscriptionDescription": "Subscription description",
  "regSms": "You've been successfully subscribed to New Subscription", 
  "unregSms": "You have successfully unsubscribed from New Subscription",
  "senderName": "IdeabizLK",
  "subscriptionUrl": "https://apps.ideabiz.lk/notify", 
  "operator": "Dialog",
  "apiVersion": "V3",
  "defaultConfig": true,
  "comment": "comment",
  "paymentV4Config":{
     "maxAmount":500
  }
}

Request for Pin Subscription (Pin Subscription )

Given below is a sample request:

URL

https://ideabiz.lk/apicall/submn/v1.0/new

Sample

https://ideabiz.lk/apicall/submn/v1.0/new

Method

POST

Body

{
    "subscriptionName": "New Subscription",
    "subscriptionDescription": "Subscription description",
    "regSms": "You've been successfully subscribed to New Subscription",
    "unregSms": "You have successfully unsubscribed from New Subscription",
    "senderName": "IdeabizLK",
    "subscriptionUrl": "https://apps.ideabiz.lk/notify",
    "operator": "Dialog",
    "apiVersion": "V3",
    "defaultConfig": true,
    "comment": "comment",
    "pinSubscriptionConfig": {
        "allowedPrefix": "9477;9476;",
        "senderName": "ideabizLK",
        "pinLen": 6,
        "pinMsg": "<#> Your PIN is ##PIN## for ##APPNAME##  KEY"
    }
}

Request with all configurations

Given below is a sample request:

URL

https://ideabiz.lk/apicall/submn/v1.0/new

Sample

https://ideabiz.lk/apicall/submn/v1.0/new

Method

POST

Body

{
    "subscriptionName": "New Subscription",
    "subscriptionDescription": "Subscription description",
    "regSms": "You've been successfully subscribed to New Subscription",
    "unregSms": "You have successfully unsubscribed from New Subscription",
    "senderName": "IdeabizLK",
    "subscriptionUrl": "https://apps.ideabiz.lk/notify",
    "operator": "Dialog",
    "apiVersion": "V3",
    "defaultConfig": true,
    "comment": "comment",
    "subscriptionSms": {
        "smsRegCode": "REG APP",
        "smsUnregCode": "UNREG APP",
        "smsNotifyUrl": "https://apps.ideabiz.lk/notify",
        "keyword": "HEY",
        "operator": "Dialog"
    },
    "subscriptionUssd": {
        "ussdRegKeyword": 456,
        "ussdUnregKeyword": 123,
        "ussdWelcomeMsg": "Welcome!",
        "ussdUnregMsg": "Thank you for using the service!",
        "operator": "Dialog",
        "ussdNotifyUrl": "https://apps.ideabiz.lk/notify"
    },
    "paymentV4Config": {
        "maxAmount": 500
    },
    "pinSubscriptionConfig": {
        "allowedPrefix": "9477;9476;",
        "senderName": "ideabizLK",
        "pinLen": 6,
        "pinMsg": "<#> Your PIN is ##PIN## for ##APPNAME##  KEY"
    }
}



Response

Given below is a sample response from the subscription manager: 

{
    "subscriptionName": "New Subscription",
    "serviceID": "8316f127-8fa5-419f-9250-cff8043be66b",
    "timestamp": "2019-01-20 11:40:45",
    "api": "Subscription",
    "status": "CREATED",
    "message": "Subscription successfully created, awaiting approval.",
    "errorCode": "0"
}

Sample Notification

Given below is a sample notification once a subscription is approved:

{
    "subscriptionName": "New Subscription",
    "serviceID": "8316f127-8fa5-419f-9250-cff8043be66b",
    "timestamp": "2019-01-20 11:40:46",
    "api": "Subscription",
    "status": "APPROVED",
    "message": null,
    "errorCode": null
}

States of Parameters

States of the Request parameters of send service.

Parameter Name

Description

Type

Mandatory /Optional

subscriptionName

The subscription name, it should be unique per application(i.e One application cannot contain two subscriptions of the name "Subscription", the API will reject this request).

string

Mandatory

subscriptionDescription

A brief description of the subscription.

string

Mandatory

regSms

SMS sent once the user subscribes to the subscription/service.

string

Mandatory

unregSms

SMS sent once the user unsubscribes from the subscription/service.

string

Mandatory

senderName

Use this only if you want to show a number other than the senderAddress for the recipient to respond to, or if you want to show an Alphanumeric port (Mask) in the SMS recipients phone.

If this is kept blank, senderAddress will be used in its place.

A Mask (Maximum 11 Char) has to be approved & configured by the ideabiz Support team before it can be used.

Mask cannot contain special characters such as ~!@#$%^&_=+-()`;:'"/?.,<>

string

Optional

subscriptionUrl

Notification URL for subscriptions

string

Mandatory

operator

Operator(Dialog)

string

Optional

comment

Any comments to be noted by the support team/business team.

string

Optional

SMS Reg Code

SMS sent once the user subscribes to the subscription/service.

string

Mandatory, if you require SMS subscriptions

SMS Unreg Code

SMS sent once the user unsubscribes from the subscription/service.

string

Mandatory, if you require SMS subscriptions

SMS Notify URL

The URL to which you would like to receive a notification of delivery of SMS.

string

Mandatory, if you require SMS subscriptions

Keyword

SMS Keyword

string

Mandatory, if you require SMS subscriptions

operator

Operator(Dialog)

string

Optional

USSD Reg Keyword

USSD keyword to register to the subscription.(When a short code/port is shared among multiple applications, the keyword should be used to uniquely identify the application.NOTE: This parameter can be empty if the short code is unique for an application)

string

Mandatory, if you require USSD subscriptions

USSD Unreg Keyword

USSD keyword to unregister from the subscription.

string

Mandatory, if you require USSD subscriptions

USSD Notify URL

If the user responds to the USSD menu, the response should be forwarded to this URL.

string

Mandatory, if you require USSD subscriptions

USSD Welcome Message

The welcome message which is displayed once the user is subscribed.

string

Mandatory, if you require USSD subscriptions

USSD Unreg Message

The Unreg message which is displayed once the user is unsubscribed.

string

Mandatory, if you require USSD subscriptions

senderName

Use this only if you want to show a number other than the senderAddress for the recipient to respond to, or if you want to show an Alphanumeric port (Mask) in the SMS recipients phone.

If this is kept blank, senderAddress will be used in its place.

A Mask (Maximum 11 Char) has to be approved & configured by the ideabiz Support team before it can be used.

Mask cannot contain special characters such as ~!@#$%^&_=+-()`;:'"/?.,<>

string

Mandatory, if you require Pin Subscription

allowedPrefix

The prefixes which are allowed to be subscribed to the service.It should contain the country code along with the operator code(Eg:9477;9476;).After each code there should be a semi-colon(;).

string

Mandatory, if you require Pin Subscription

pinLen

The length of the PIN sent to the user. It's usually set at 6.

string

Mandatory, if you require Pin Subscription

pinMsg

If you require a customized pin message, send this in the request body.As seen in the example above (<#> Your PIN is ##PIN## for ##APPNAME## KEY) the placeholders for PIN and APPNAME are mandatory. The KEY is your Google OTP hash.

string

Optional, if you require Pin Subscription



Response Codes

200 – Success!
400 – Bad request; check the error message for details
401 – Authentication failure, check your authentication details
403 – Forbidden; please provide authentication credentials
404 – Not found: mistake in the host or path of the service URI
405 – Method not supported: for example you mistakenly used a HTTP GET instead of a POST
500 – The server encountered an unexpected condition. This could be wrong authentication details or limited user permission
503 – Server busy and service unavailable. Please retry the request.

Last updated on 12th Dec 2019