Get SMS account balance
GET /api/communications/sms/balance
- Products: Operator (
FOH) - Features: Front of House Generic Access (
FOHGENERIC)
Overview
Returns the SMS credits remaining for this tenant with Power2, the third-party gateway Gladstone uses to send text messages.
The figure is fetched from Power2 on every call rather than read from a local counter, so it reflects anything that has consumed the sub-account's credits, and the call is as slow and as fallible as the round trip to Power2. The body is the balance as Power2 reports it — a single field, sms_credits, carrying the count as a string.
The tenant must already have a Power2 sub-account for this to work; create one with Create Power2 sub account with credit transfer. Before that, and where the environment has no Power2 credentials configured, the call fails with 404 rather than returning a zero balance.
Endpoint
GET {base_url}/api/communications/sms/balance
{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.
Sample request
curl -X GET '{base_url}/api/communications/sms/balance' \
-H 'Authorization: Bearer {accessToken}' \
-H 'X-Use-SSO: true'Errors
| Status | Meaning | When |
|---|---|---|
400 | Bad request | Power2 rejected the balance request, or answered with an unsuccessful HTTP status. The response body is Power2's own error text, passed through unchanged. |
404 | Not found | The tenant has no Power2 sub-account name or sender id recorded (Attempting to retrieve Power2Sms sub account name but the sub account name does not exist.), or the environment has no Power2 user name, secret key or main account name configured. |
500 | Internal server error | An unexpected failure while calling Power2 or parsing its answer. The response has no body. |
Notes
- Straight after Create Power2 sub account with credit transfer succeeds, this call can take up to 20 minutes to use the new sub-account. In that time it can still return
404(on a first set-up) or the balance of the previous sub-account (after a repeat set-up). Wait 20 minutes before relying on the figure.