Admin Api V2
Admin API
This API will provide the facility to query subscribers of the application and to deactivate if necessary. Every service provider needs to implement an admin API as per below specification and communicate the end point to Dialog Ideabiz team. This API will be connected with Admin interface for Dialog customer care frontline to query and to take necessary actions as per customer's request. Through the Admin API URL, notifications can be received whenever subscribers' status change. (eg: Status 'SUBSCRIBED' or Status 'UNSUBSCRIBED' and the method of subscription). Admin API notifications give you an overall view of all the status changes of subscribers, and functions as a method of cross-checking subscriber status in your application.
Version : 2
Date : 2016-06-26
Sample Codes
Java classes models
https://github.com/ideabizlk/Ideabiz-adminapp-common-models
Java Spring Sample service
https://github.com/ideabizlk/Ideabiz-adminapp-remote-api
API Specification
Search Subscribers
Searching a subscriber in an application
Method : POST
Accept : application/json
Example
http://myapp.com/adminapi/
http://myapp.com/adminapi/index.php
METHOD
POST
Request Body
{
"action" : "STATE_CHECK",
"msisdn" : "94777123456",
"serviceID" : "SVC_001",
"appID" : "APP_001"
}
Field | Description | Mandatory |
---|---|---|
serviceID | micro subscription ID | Optional |
appID | application ID in ideabiz | Mandatory |
Response Body
{
"statusCode": "SUCCESS",
"message": "",
"data": {
"subscription": [{
"msisdn":"94777123456",
"appID":"APP_001",
"serviceID" : "SVC_001",
"registration-log" :{
"datetime" : "2016-01-12 12:33:33",
"method" : "WEB"
},
"unregistration-log" :{
"datetime" : "2016-01-12 12:33:33",
"method" : "WEB"
},
"status":"REGISTERED",
"microSubscriptions" : 0
}]
}
}
Field | Description | Mandatory |
---|---|---|
number | Subscriber mobile number. Eg: 94766691500 (If Encrypted : 9477-vl%1D%A3%F7%AC%E1%A7%C7%AF) | Mandatory |
status | Current status UNSUBSCRIBED : User already unsubscribed SUBSCRIBED : User has active subscription |
Mandatory |
registration | User registration info | Mandatory |
registration -> datetime | User registration timestamp | Mandatory |
registration -> method | User registration method values : SMS, WebWidget, USSD | Mandatory |
unregistration | User registration infoif there is no unregistration information, this should null | Optional |
unregistration -> datetime | User registration timestamp | Mandatory |
unregistration -> method | User un-registration method values : SMS, WEB, USSD, CC | Mandatory |
microSubscriptions | If the app has micro subscriptions | Optional |
serviceID | If you have multiple subscriptions under one app, this should return service ID | Optional |
History
Similar to the above method of searching a subscriber this will return the history of the subscriber of your application. The difference is that pagination is available for history.
Request Body
{
"action" : "HISTORY",
"msisdn" : "94766691500",
"appID" : "APP001",
"serviceID" : "SVC_001",
"offset" : 0,
"limit" : 10
}
Response Body
{
"subscriberHistory": {
"msisdn" : "94766691500",
"appID" : "APP001",
"serviceID" : "SVC_001",
"offset" : 0,
"limit" : 10
"history": [
{
"datetime": "2014-05-20 10:33:11",
"trigger": "ADMIN",
"event": "UNSUBSCRIBE",
"note": "",
"status": "SUCCESS",
"serviceID" : null
},
{
"datetime": "2014-05-20 10:33:11",
"trigger": "SYSTEM",
"event": "CHARGING",
"note": "no funds",
"status": "FAILED",
"content" : "LKR 3.00",
"serviceID" : "SVC_001"
},
{
"datetime": "2014-05-20 10:33:11",
"trigger": "SYSTEM",
"event": "SMS",
"note": "",
"content" : "Today quote is...",
"status": "SUCCESS"
"serviceID" : null
},
{
"datetime": "2014-05-20 10:33:11",
"trigger": "SUBSCRIBER",
"event": "SUBSCRIBE",
"note": "",
"status": "SUCCESS"
}
]
}
}
Field | Description | Mandatory |
---|---|---|
number | Subscriber mobile number. Eg: 94766691500 | Mandatory |
offset | Offset of current response | Mandatory |
limit | Limit of current response | Mandatory |
history | Last 10 events regarding the specific user This array contains object of history |
Mandatory |
history -> datetime | Event timestamp | Mandatory |
history -> trigger | Actor of the trigerred event. Eg : SYSTEM,SUBSCRIBER,ADMIN |
Mandatory |
history -> event | Event type Eg: SUBSCRIBE, UNSUBSCRIBE, SMS, USSD, CHARGING |
Mandatory |
history -> note | Any note as string | Mandatory |
history -> status | Specific event status Eg : SUCCESS, FAILED |
Mandatory |
Not Found
{
"subscription": {
"number": "94777123456",
"status": "NOTFOUND"
}
}
Field | Description | Mandatory |
---|---|---|
number | Subscriber mobile number. Eg: 94777123456 | Mandatory |
status | current status NOTFOUND : User subscription not found |
Mandatory |
Subscribe / Unsubscribe user from app or service
Based on the user's state change, we will send a json to your notify URL. You can cross check the status of the user as per your application records and update accordingly.
1) When a user subscribes to the app/service we will send the following json:
Request Body
{
"action":"STATE_CHANGE",
"method":"WEB",
"msisdn":"tel:+94777123456",
"appID":"APP001",
"serviceID":"SVC_001",
"status":"SUBSCRIBED"
}
2) When a user unsubscribes from the app/service we will send the following json:
Request Body
{
"action":"STATE_CHANGE",
"method":"WEB",
"msisdn":"94777123456",
"appID":"APP001",
"serviceID":"SVC_001",
"status":"UNSUBSCRIBED"
}
Security check for incoming API call.
Upon receiving an API call, please validate the IP
IP Validation
Source IP : 202.69.200.34
Rental charging responses
1. When user was charged successfully on subscription
{
"action":"STATE_CHANGE",
"method":"RENTAL",
"msisdn":"766691500",
"appID":"545",
"serviceID":"0401f3c2-d2dd-4a25-bb30-4fe4cabbe988",
"status":"SUBSCRIBE"
}
2. when user was not charged on renewal attempts
{
"action":"STATE_CHANGE",
"method":"RENTAL",
"msisdn":"766691500",
"appID":"545",
"serviceID":"0401f3c2-d2dd-4a25-bb30-4fe4cabbe988",
"status":"RENTAL_FAILED"
}
3. When user was charged successfully after a period of failed payment/s
{
"action":"STATE_CHANGE",
"method":"RENTAL",
"msisdn":"766691500",
"appID":"545",
"serviceID":"0401f3c2-d2dd-4a25-bb30-4fe4cabbe988",
"status":"RENTAL_CHARGED"
}
4. When the user got unregistered
{
"action":"STATE_CHANGE",
"method":"RENTAL",
"msisdn":"766691500",
"appID":"545",
"serviceID":"0401f3c2-d2dd-4a25-bb30-4fe4cabbe988",
"status":"UNSUSCRIBE"
}