Skip to content

Balance Check API

Content

Overview

The Dialog Balance Check API allows you to obtain the account balance information of a user. Balance check services are accessible via RESTful web services.

Method

The following REST methods are available: + Obtaining the account balance information of a user.

Requirements

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) documentation for Authorization.

Request Header 

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

Sample Request Header 

Authorization: Bearer a92ba8hjgjhgjh3fa1609cabcd79
Accept: application/json
Content-Type: application/json
All API calls to Ideabiz require an OAuth 2.0 Bearer Access Token in the request headers.

[!TIP] Need an Access Token? Follow the Token Management Guide to generate or renew your token.

Key Concepts & Jargon Buster

  • Prepaid vs. Postpaid:
  • PREPAID: The customer pays in advance. The balance field indicates their current available airtime (in LKR).
  • POSTPAID: The customer pays monthly. The creditLimit indicates their maximum credit ceiling, and balance indicates their remaining unbilled credit limit.
  • Plain MSISDN: Standard mobile number formatted with country code (e.g., 94766691500).
  • Encrypted MSISDN: An anonymous alphanumeric token obtained through Header Enrichment when the user browses on mobile data.

Balance Checking

This allows you to send an SMS from your Web application to one or more addresses (MSISDNs).

URL

Formatting the {MSISDN} Parameter

The {MSISDN} in the URL must be formatted depending on whether you have a Plain Number or an Encrypted Number:

Option A: Using a Plain Mobile Number

  • Use standard Sri Lankan international format: 947XXXXXXXX.
  • Do NOT include +, tel:, dashes, or leading zeros.

Example URL: 

https://ideabiz.lk/apicall/balancecheck/v3/94766691500/transactions/amount/balance

Option B: Using an Encrypted MSISDN (from Header Enrichment)

  • If you detected the user's number via Header Enrichment, the token must be URL-encoded with the etel: prefix.

https://ideabiz.lk/apicall/balancecheck/v4/{MSISDN}/transactions/amount/balance
Please note that when you add an Encrypted MSISDN, you have to URL encode it again.

Sample URL (With URL encoded Encrypted Number)

https://ideabiz.lk/apicall/balancecheck/v3/etel:9476-vl%251D%25A3%25F7%25AC%25E1%25AE%25C0%25AD%25FF/transactions/amount/balance

https://ideabiz.lk/apicall/balancecheck/v4/etel:9476-vl%251D%25A3%25F7%25AC%25E1%25AE%25C0%25AD%25FF/transactions/amount/balance

*(Refer the Header Enrichment (http://docs.ideabiz.lk/APIs/Header_Enrichment) document) *

Before adding a Plain Number to the URL please omit "tel:+"

Sample URL (With Plain Number)

 https://ideabiz.lk/apicall/balancecheck/v3/94766691500/transactions/amount/balance
Method
GET

Response

{
    "endUserId": "94766691500",
    "referenceCode": "DLG212005-1500564823863",
    "accountInfo": {
        "accountType": "PREPAID",
        "accountStatus": "Active",
        "creditLimit": 66.81,
        "balance": 66.81
    }
}


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.

Exceptions

Types

Policy Exception

Message Id start withPL

Server Exception

Message Id start with SV

Exception Body

{
    "requestError": {
        "serviceException": {
            "messageId": "SVC0002",
            "text": " Invalid input value for message part %1",
            "variables": " clientCorrelator Value 12345"
        }
    }
}

Faults

HTTP Respose code 503

Fault Response Body

{
    "fault": {
        "code": "900800",
        "message": "Message Throttled Out",
        "description": "You have exceeded your quota"
    }
}

Policy & Server Exceptions

When an error occurs at the business or platform layer, the response will contain an exception structure:

  • Policy Exception (PLxxxx): Violation of business rules (e.g., invalid subscriber account).
  • Service Exception (SVCxxxx): Malformed parameters or input format errors.