Developer10 min read

REST API reference

Subscriber lists, charging info and unsubscription: the JSON APIs you call after a subscriber exists.

Code, endpoints and integration detail.

Everything on this page is a REST API, which makes it the exception rather than the rule. The charging SDKs work by opening a signed URL in a browser; these four endpoints are ordinary JSON over HTTP, called from your server once a subscriber already exists.

A different host and a different credential

The REST APIs live on https://api.digimart.store, not on the user.digimart.store host the SDKs use. They also authenticate differently: instead of an API Key and a SHA-512 signature, every request carries your applicationId and the password you were given when the application was provisioned.

What they are for

Subscriber list pages through everyone registered against your application.
Subscriber charging info answers whether specific people are still subscribed and when they last paid.
User unsubscription ends a subscription. This is the endpoint behind any cancel control you build, and a working cancellation path is a condition of the developer agreement.
Subscriber notifications is the odd one out: Digimart calls it on you.

Conventions

Every request and response is application/json;charset=utf-8.
Every call is a POST, including the read-only ones.
Subscribers are identified by tel:<msisdn>. If your application uses masked numbers, send the masked value: it is the same value the charging SDK handed you as subscriberId.
statusCode reports the outcome of the request as a whole, and list responses repeat a per-subscriber statusCode for each entry.

Status codes

The published specification constrains the subscriber-list statusCode to the values below. It does not give a description for each one, so none is invented here. The SDK error codes documented on Error codes are a separate set and do not apply to these endpoints.

Permitted REST status codes
Code	Kind
`S1000`	Success
`S1001`	Success
`E1100`	Error
`E1102`	Error
`E1103`	Error
`E1104`	Error
`E1105`	Error
`E1106`	Error
`E1107`	Error

Endpoints

POST/subscription-info-server/getSubscribers

Subscriber list

Returns the subscribers registered against your application, one page at a time. Use it to reconcile your own records against the platform's.

https://api.digimart.store/subscription-info-server/getSubscribers

Request body

application/json;charset=utf-8

Request fields for /subscription-info-server/getSubscribers
Name	Type	Required	Description
`applicationId`	string	Required	Unique identification of the application within the platform. Only a single value can be sent per request. `APP_102672`
`password`	string	Required	Password given when provisioning the application. Used to authenticate the application against the service provider's credentials. `cf2b9e361c13bc54b86d3c8180b0582fd`
`requestPage`	integer	Required	The page number to fetch from the list of subscription notifications. `2`
`version`	string	Optional	The version of the API being invoked. `2.0`
`status`	string	Optional	Filter by subscription entry status.`REGISTEREDTEMPORARY_BLOCKEDREG_PENDING`
`subscriberRequestId`	string	Optional	The initial request ID allocated when the Charging SDK transaction was triggered for a particular user. `124002601656523239`

{
  "applicationId": "APP_102672",
  "password": "cf2b9e361c13bc54b86d3c8180b0582fd",
  "version": "2.0",
  "status": "REGISTERED",
  "subscriberRequestId": "124002601656523239",
  "requestPage": 2
}

Response

Response fields for /subscription-info-server/getSubscribers
Name	Type	Required	Description
`version`	string	Required	The version of the API being invoked. `2.0`
`statusCode`	string	Required	Success or error code for the entire request. `S1000`
`statusDetail`	string	Required	Description corresponding to the status code. `Request was successfully processed`
`nextPageNumber`	integer	Required	The next available page number. When no further page exists, -1 is returned. `3`
`moreDataAvailable`	boolean	Required	Indicates whether more data is available beyond this page. `true`
`requestId`	string	Optional	Unique identifier of this response against its request. Quote it when raising a support ticket. `223902031657423338`
`subscribers[]`	array of objects	Optional	One entry per subscriber: subscriberId, subscriberRequestId, subscriptionStatus, lastChargedDate and lastChargedAmount.

{
  "version": "2.0",
  "statusCode": "S1000",
  "statusDetail": "Request was successfully processed",
  "nextPageNumber": 3,
  "moreDataAvailable": true,
  "requestId": "223902031657423338",
  "subscribers": [
    {
      "subscriberId": "tel: NTM3MDgzMWI2ZDAwMzlmZTQ0N2Y1ZGFhMzQwOTM2MDA0YmEzZWRiYTFjYzIzNzhhZDZhYjZjNmI1MzliZWIxYTpiYW5nbGFsaW5r",
      "subscriberRequestId": "124002601656523239",
      "subscriptionStatus": "REGISTERED",
      "lastChargedDate": "2020-01-23 22.03.22",
      "lastChargedAmount": "30.00 BDT"
    }
  ]
}

POST/subscription/getSubscriberChargingInfo

Subscriber charging info

Looks up the current subscription state and last charge for a list of subscribers. Answers 'is this person still subscribed, and when did they last pay'.

https://api.digimart.store/subscription/getSubscriberChargingInfo

Request body

application/json;charset=utf-8

Request fields for /subscription/getSubscriberChargingInfo
Name	Type	Required	Description
`applicationId`	string	Required	Unique identification of the application within the platform. Only a single value can be sent per request. `APP_102672`
`password`	string	Required	Password given when provisioning the application. Used to authenticate the application against the service provider's credentials. `cf2b9e361c13bc54b86d3c8180b0582fd`
`subscriberId`	array of strings	Optional	MSISDNs of the subscribers to look up. If your application uses masked numbers, send the masked values here. `tel: 8801740812854 or tel: NTM3MDgzMWI2ZDAwMzlmZTQ0N2Y1ZGFhMzQwOTM2MDA0YmEzZWRiYTFjYzIzNzhhZDZhYjZjNmI1MzliZWIxYTpiYW5nbGFsaW5r`

{
  "applicationId": "APP_102672",
  "password": "cf2b9e361c13bc54b86d3c8180b0582fd",
  "subscriberId": [
    "tel: NTM3MDgzMWI2ZDAwMzlmZTQ0N2Y1ZGFhMzQwOTM2MDA0YmEzZWRiYTFjYzIzNzhhZDZhYjZjNmI1MzliZWIxYTpiYW5nbGFsaW5r",
    "tel: HTM3MDgzMWI2ZDAwMzlmZTQ0N2Y1ZGFhMzQwOTM2MDA0YmEzZWRiYTFjYzIzNzhhZDZhYjZjNmI1MzliZWIxYTpiYW5GFsaW5rtf",
    "tel: lkFgzMWI2ZDAwMzlmZTQ0N2Y1ZGFhMzQwOTM2MDA0YmEzZWRiYTFjYzIzNzhhZDZhYjZjNmI1MzliZWIxYTpiYW5nbGFsaW5r"
  ]
}

Response

Response fields for /subscription/getSubscriberChargingInfo
Name	Type	Required	Description
`version`	string	Required	The version of the API being invoked. `2.0`
`statusCode`	string	Required	The status code for the entire request. `S1000`
`statusDetail`	string	Required	Description corresponding to the status code. `Success.`
`requestId`	string	Optional	Unique identifier of this response against its request. Quote it when raising a support ticket. `101901031657410007`
`destinationResponses[]`	array of objects	Required	Per-subscriber result: subscriberId, subscriptionStatus, subscriberRequestId, lastChargedDate, lastChargedAmount, numberType (prepaid or postpaid), and its own statusCode and statusDetail.

{
  "version": "2.0",
  "statusCode": "S1000",
  "statusDetail": "Success.",
  "requestId": "101901031657410007",
  "destinationResponses": [
    {
      "subscriberId": "tel: 8801740812854",
      "subscriptionStatus": "REGISTERED",
      "subscriberRequestId": "124002601656523239",
      "lastChargedDate": "2020-01-23 22.03.22",
      "lastChargedAmount": "30.00 BDT",
      "numberType": "postpaid",
      "statusCode": "S1000",
      "statusDetail": "Request was successfully processed"
    }
  ]
}

POST/subs/unregistration

User unsubscription

Ends a subscriber's subscription to your application. This is the API behind any 'cancel my subscription' control you build.

https://api.digimart.store/subs/unregistration

Request body

application/json;charset=utf-8

Request fields for /subs/unregistration
Name	Type	Required	Description
`applicationId`	string	Required	Unique identification of the application within the platform. Only a single value can be sent per request. `APP_999999`
`password`	string	Required	Password given when provisioning the application. Used to authenticate the application against the service provider's credentials. `95904999aa8edb0c038b3295fdd271de`
`subscriberId`	string	Required	The subscriber to unsubscribe, as tel:<msisdn>. This may be a masked number depending on the application type. Only a single value can be sent per request. `tel:NTM3MDgzMWI2ZDAwMzlmZTQ0N2Y1ZGFhMzQwOTM2MDA0YmEzZWRiYTFjYzIzNzhhZDZhYjZjNmI1MzliZWIxYTpiYW5nbGFsaW5r`
`action`	string	Required	The operation to perform. 0 means user unsubscription.`0`

{
  "applicationId": "APP_999999",
  "password": "95904999aa8edb0c038b3295fdd271de",
  "subscriberId": "tel:NTM3MDgzMWI2ZDAwMzlmZTQ0N2Y1ZGFhMzQwOTM2MDA0YmEzZWRiYTFjYzIzNzhhZDZhYjZjNmI1MzliZWIxYTpiYW5nbGFsaW5r",
  "action": "0"
}

Response

Response fields for /subs/unregistration
Name	Type	Required	Description
`version`	string	Required	The version of the API being invoked. `2.0`
`statusCode`	string	Required	The status code for the entire request. `S1000`
`statusDetail`	string	Required	Description corresponding to the status code. `not registered`
`requestId`	string	Optional	Unique identifier of this response against its request. Quote it when raising a support ticket. `101901031657410007`
`subscriptionStatus`	string	Required	The resulting subscription status. `UNREGISTERED`

{
  "version": "2.0",
  "statusCode": "S1000",
  "statusDetail": "not registered",
  "requestId": "101901031657410007",
  "subscriptionStatus": "UNREGISTERED"
}

POST/subscription/notifyYou implement this

Subscriber notifications

Digimart calls this one, not you. Implement it at the URL you set on your application and Digimart will post subscription lifecycle changes to it. Reply 200 quickly and process asynchronously.

Body Digimart sends you

Response fields for /subscription/notify
Name	Type	Required	Description
`timeStamp`	string	Required	The time the request was sent. `20120113082110`
`subscriberId`	string	Required	The subscriber the notification concerns, masked if your application uses masked numbers.
`applicationId`	string	Required	Unique identification of the application within the platform. Only a single value can be sent per request. `APP_000842`
`version`	string	Required	The version of the API being invoked. `2.0`
`frequency`	string	Required	How often the subscription is billed.`dailymonthly`
`status`	string	Required	Status of the subscription entry.`REGISTEREDTEMPORARY_BLOCKEDREG_PENDING`
`subscriberRequestId`	string	Optional	The initial request ID allocated when the Charging SDK transaction was triggered for this user. `101901031657410007`

{
  "timeStamp": "20120113082110",
  "subscriberId": "NTM3MDgzMWI2ZDAwMzlmZTQ0N2Y1ZGFhMzQwOTM2MDA0YmEzZWRiYTFjYzIzNzhhZDZhYjZjNmI1MzliZWIxYQ==",
  "applicationId": "APP_000842",
  "version": "2.0",
  "frequency": "daily",
  "status": "REGISTERED",
  "subscriberRequestId": "101901031657410007"
}

Where this came from

Every field, type, example and enum on this page is transcribed from the OpenAPI 3.0 specification published at digimart.store/API_Documentation. The specification ships code samples marked "coming soon" for Java, PHP, JavaScript and .NET, so no per-language examples are reproduced here.

Subscription SDK One-time SDK Error codes