Skip to main content

Account Balance API

To help you stay informed of your PaaSoo account's remaining Balance in real time, PaaSoo provides an API directly for querying the Account Balance. Through this API, you can query your account's available Balance at any time, allowing you to promptly address funding control, prepay/recharge, or Billing settlement needs for your SMS business.

1. Invocation Method​

Invocation Method
  • HTTP Method: GET
  • Endpoint: https://api.paasoo.com/balance
  • Usage Scenario: You can call this API when you need to obtain the current account or sub-account (if tiered) Balance before, during, or after SMS sending to evaluate whether it meets the requirements for continued sending.

2. Request Example​

GET https://api.paasoo.com/balance?key=API_KEY&secret=API_SECRET

3. Request Parameters​

ParameterTypeRequiredDescriptionExample
keystringYesAPI Key (composed of 8 alphanumeric characters), used to uniquely identify your account. Can be obtained in the PaaSoo dashboard.Abcdefgh
secretstringYesAPI Secret (composed of 8 alphanumeric characters), used in conjunction with key for authentication. Can be obtained in the PaaSoo dashboard.Abc123EF

4. Response Example​

Upon a successful query, you will receive the current Account Balance and Currency unit; if the query fails, an error code and corresponding message will be returned.

4.1 Response Parameters​

ParameterTypeDescriptionExample
codeintegerResponse status. The response status code submitted to the PaaSoo cloud communication platform. Generally, 0 represents success.0
descrstringStatus description information corresponding to code, used to explain the reason for the error or detailed status.Missing parameters
balancestringCurrent Account Balance. This value may contain a decimal part, and the specific precision depends on the account type or Currency unit.1234.56
creditLimitstringCurrent account credit limit. This value may contain a decimal part, and the specific precision depends on the account type or Currency unit.0
currencystringThe Currency unit or symbol corresponding to the Account Balance, such as USD, SGD, CNY, etc.USD

4.2 Success Response Example​

{
    "balance": "9999.99999",
    "creditLimit": "-1000",
    "currency": "EUR"
}

4.3 Failure Response Example​

{
    "code": 4,
    "descr": "Invalid credentials"
}

5. API Status Code List​

  • 0 - success: Success
  • 2 - Missing parameters: Required parameters are missing
  • 3 - Invalid parameters: Parameter format error
  • 4 - Invalid credentials: Key or Secret error
  • 5 - Unauthorized IP: IP Whitelist restriction
  • 11 - System error: System error

6. Best Practices and Precautions​

  1. Invocation Frequency:
    • Please design a reasonable query frequency based on your business volume to avoid putting too much pressure on the server. Overly frequent queries may trigger Throttling.
  2. Security:
    • Ensure this API is called over an HTTPS channel to prevent sensitive information like key and secret from being stolen.
    • Consider implementing access restrictions via an IP Whitelist to further enhance the security level.
  3. Limit Monitoring:
    • Before large-scale SMS sending or periodic sending, you can integrate this API into your internal system to check the Balance, and set up alerts or automatic recharges when it is insufficient.
  4. Concurrent Queries:
    • If you have sub-accounts or multiple business modules sharing the same account, make sure to control the query frequency and estimate Balance usage to avoid sending failures due to exceeding limits or contention.

7. Summary​

Through this real-time Account Balance API, you can obtain your currently available Balance and its Currency at any time, without manually logging into the dashboard or waiting for daily or periodic reconciliation notifications. By combining it with other PaaSoo SMS APIs, Batch Status APIs, and Callback URL For Delivery Receipts, you can achieve automated and fine-grained monitoring and management throughout the entire SMS process.

Support

If you encounter any technical issues or have business inquiries during the API integration, please do not hesitate to contact our Support team at support@paasoo.com. We are always here to assist you.