---
title: "Get Balance API (get-balance)"
description: "Retrieve the remaining TL balance and SMS quota on your account in one call. No side effects, no credit consumed."
slug: /en/docs/api/get-balance
locale: en
audience: developer
last_updated: 2026-04-29
endpoint:
  method: POST
  path: /v1/get-balance/json
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [authentication, send-sms, get-report, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/get-balance
  en: https://www.iletimerkezi.com/en/docs/api/get-balance
  toplusmsapi: https://toplusmsapi.com/account/balance/json
  a2psmsapi: https://a2psmsapi.com/en/account/balance/json
---

# 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](./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

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

## Response

### Success (200)

```json
{
  "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`](https://github.com/iletimerkezi/apidocs-website/issues/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](./authentication.md).

#### Other error codes

For `400, 404`: see [error-codes.md](./error-codes.md).

## Code samples

### cURL

```bash
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`](./get-report.md) 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.


## Related

- [Authentication](./authentication.md)
- [Send SMS (send-sms)](./send-sms.md)
- [Order report (get-report)](./get-report.md)
- [Error code table](./error-codes.md)