Get Balance API (get-balance)

The get-balance endpoint returns the TL balance remaining on your account and the number of standard SMS messages that balance can fund. It has no side effects and consumes no credits, making it the safest call for verifying authentication and checking remaining budget before a campaign.

Prerequisite: enable API access in the panel

Before calling this endpoint, the Allow API access toggle must be on in your iletiMerkezi panel.
Location: panel.iletimerkezi.com → Settings → Security → Access Permissions
If it is off, every request returns 401 — Üyelik bilgileri hatalı ("Authentication failed"). See authentication.md.

Endpoint

| Field | Value | |---|---| | Method | POST | | URL | https://api.iletimerkezi.com/v1/get-balance/json | | Content-Type | application/json | | Auth | API Key + Hash (request.authentication) |

Request

Schema

request
└─ authentication
   ├─ key (string, required)
   └─ hash (string, required)

get-balance takes no extra fields beyond the auth block.

Full example

{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    }
  }
}

Response

Success (200)

{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "balance": {
      "amount": 10.584,
      "sms": 67
    }
  }
}

İşlem başarılı means "Request successful" in Turkish.

Fields:

response.status.code (integer): internal status code, mirrors the HTTP code.
response.status.message (string): human-readable Turkish message.
response.balance.amount (number, float): remaining balance in Turkish Lira (TRY).
response.balance.sms (integer): standard SMS count that balance can fund (an estimate based on average sender / carrier rates).

Older versions of the apidocs-website spec list amount and sms as strings; the live API returns them as number / integer. We treat the live API as ground truth (drift: apidocs-website#1). In TypeScript, response.balance.amount is directly typed as number.

Error responses

401 — Üyelik bilgileri hatalı ("Authentication failed")

API Key / Hash invalid, or the panel toggle is off. See authentication.md.

Other error codes

For 400, 404: see error-codes.md.

Code samples

cURL

curl -X POST 'https://api.iletimerkezi.com/v1/get-balance/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      }
    }
  }'

Common pitfalls

amount is a number, not a string. Older examples may show "amount": "0"; the live API returns amount: 10.584 (number/float). Don't add a string-to-number cast in your parser.
sms is an integer. Examples like "sms": "18343" belong to the old spec; the actual value is integer (67).
get-balance consumes no credits. Use it freely to verify auth and check budget before send-sms. Don't poll it from a webhook or cron at high frequency, though — it's wasteful.
sms is an estimate. Carrier rates and message length (long text, UCS-2) shift the real count slightly. For exact post-send accounting, read price from the get-report response.
Balance drops at send-sms 200, not at delivery. Credits are debited the moment the order is queued; the API does not wait for carrier ack.

Last updated: 2026-04-29 · Türkçe