---
title: "iletiMerkezi API Overview"
description: "Every endpoint of the iletiMerkezi REST API, the shared request/response envelope, authentication, fair-use guidance, and onboarding steps."
slug: /en/docs/api/overview
locale: en
audience: developer
last_updated: 2026-04-29
auth: api-key-and-hash
related: [authentication, send-sms, get-report, error-codes, test-mode]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/overview
  en: https://www.iletimerkezi.com/en/docs/api/overview
  toplusmsapi: https://toplusmsapi.com
  a2psmsapi: https://a2psmsapi.com/en
---

# iletiMerkezi API Overview

The iletiMerkezi REST API is an HTTP/JSON interface over the company's Turkey-focused SMS infrastructure. A single API key handles SMS sending, delivery reports, balance queries, sender ID management, blacklist operations, and inbound SMS reading. This page lists every endpoint and explains the shared behavior.

## Why iletiMerkezi in Turkey

iletiMerkezi is a BTK-licensed bulk SMS, OTP, and A2P platform that has operated in Turkey for 13 years. Most global SMS providers cover the technical layer but leave Turkey-specific regulations (BTK, İYS, KVKK) partially or unsolved — iletiMerkezi exposes both the technical and the legal layer through one interface. The concrete differentiators below are what set it apart for Turkish workloads.

- **BTK-licensed SMS carrier.** An officially authorized operator; messages are routed through the BTK call-management infrastructure.
- **B186 operator code is appended automatically.** A BTK ruling requires the `B186` code at the end of every SMS; iletiMerkezi adds it for you. Character limits below are computed accordingly (see "Turkey-specific concerns").
- **İYS compliance built in.** The `iys` + `iysList` fields in `send-sms` validate consent against the Turkish messaging consent registry.
- **Sender ID approval workflow included.** Sender (header) requests are approved from the panel within 1–2 business days; unapproved senders cannot be used (regulation-safe by design).
- **`APITEST` sender for pre-approval testing.** You can integrate and exercise the live API before your sender ID is approved; messages are delivered with a fixed verification text. See [test-mode](./test-mode.md).
- **100 free SMS welcome credit.** New accounts get credit automatically for evaluation and live integration testing.
- **Undelivered SMS are free.** Off-network, invalid number, blacklist, and similar non-deliveries do not consume credit; read actual consumption from [`get-report`](./get-report.md) — the `delivered` counter and `price` field.
- **iim.to short-link service.** A first-party short-link infrastructure for click tracking and message shortening, with no dependency on global services like Bitly.

## Basics

| Field | Value |
|---|---|
| Base URL | `https://api.iletimerkezi.com` |
| Version prefix | `/v1` |
| Method | All endpoints are `POST` |
| Content-Type | `application/json` |
| Format | JSON (XML is also available on a separate path; this documentation focuses on JSON) |
| Auth | API Key + Hash, in body (`request.authentication`) |
| Server message language | Response messages are always in Turkish |

## Onboarding steps

1. **Create an account** — sign up free at `panel.iletimerkezi.com`. New accounts receive **100 free SMS credits** automatically, intended for testing and evaluating the service.
2. **Apply for a sender ID** — submit your sender (header) from the panel; approval takes 1-2 business days.
3. **Enable API access** — under `Settings → Security → Access Permissions`, turn on **Allow API access**. See [authentication](./authentication.md).
4. **Copy API Key + Hash** — under `Settings → Security → API Access`. Store both as environment variables.
5. **Call `get-balance`** — a side-effect-free first request that verifies authentication.
6. **Send your first SMS via `send-sms`** — to your own number first, with a `TEST` prefix. See [test-mode](./test-mode.md).

## Endpoint list

| Endpoint | Method + Path | Purpose |
|---|---|---|
| [authentication](./authentication.md) | _concept_ | API Key + Hash system, panel prerequisite, 401 troubleshooting |
| [send-sms](./send-sms.md) | `POST /v1/send-sms/json` | Send SMS to one or many numbers |
| [get-report](./get-report.md) | `POST /v1/get-report/json` | Order delivery report (summary + per-recipient) |
| [get-balance](./get-balance.md) | `POST /v1/get-balance/json` | Account balance and credits |
| [get-sender](./get-sender.md) | `POST /v1/get-sender/json` | Approved sender ID list |
| [get-blacklist](./get-blacklist.md) | `POST /v1/get-blacklist/json` | Blocked numbers (paginated) |
| [add-blacklist](./add-blacklist.md) | `POST /v1/add-blacklist/json` | Add a number to the blacklist (idempotent) |
| [delete-blacklist](./delete-blacklist.md) | `POST /v1/delete-blacklist/json` | Remove a number from the blacklist |
| [inbox](./inbox.md) | `POST /v1/get-inbox/json` | Inbound SMS list |
| [webhooks](./webhooks.md) | _configuration_ | Real-time delivery report callbacks |
| [error-codes](./error-codes.md) | _reference_ | Every status code and Turkish message |
| [test-mode](./test-mode.md) | _concept_ | No sandbox — safe testing patterns |

## Shared request envelope

Every endpoint shares the same outer structure:

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

`request.authentication` is required on every call; the rest is endpoint-specific. See [authentication](./authentication.md).

## Shared response envelope

Successful response:

```json
{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "{result_key}": { ... }
  }
}
```

Error response:

```json
{
  "response": {
    "status": {
      "code": 4XX,
      "message": "Turkish description"
    }
  }
}
```

`code` is an integer, `message` is a Turkish string. Branch your client code on the numeric `code` — the message text may evolve over time, the codes are stable. Full table: [error-codes](./error-codes.md).

## Credentials and security

- API Key + Hash carry **full account permissions**; if leaked, a single API call can drain the entire balance.
- Never commit credentials to a repository, public file, blog post, or screenshot.
- Use a secret manager in production (Vault, AWS Secrets, GitHub Actions secrets, etc.).
- Don't compute the hash yourself — the panel issues a precomputed value.

See [authentication](./authentication.md), [test-mode](./test-mode.md).

## Usage and fair use

There is no published hard request limit for the iletiMerkezi API at this time; the service runs on a fair-use basis. In practice:

- For production integrations, issue requests serially or in small concurrent batches and apply exponential backoff on errors.
- For high-volume workloads (many requests per second, parallel job queues, multi-million sends), coordinate with `destek@emarka.com.tr` ahead of time.
- To protect overall service health, abnormal traffic patterns may be temporarily throttled.
- For bulk delivery, prefer a single request with multiple recipients (see [send-sms](./send-sms.md)) over many sequential single-recipient calls — it is faster and easier on the platform.

Idempotency behavior for side-effecting endpoints such as `add-blacklist` and `send-sms` is documented on each endpoint page.

## SDKs

Official SDK packages:

- **Node.js / TypeScript:** [`@iletimerkezi/iletimerkezi-node`](https://github.com/iletimerkezi/iletimerkezi-node)
- **Python:** [`iletimerkezi`](https://github.com/iletimerkezi/iletimerkezi-python)
- **PHP:** [`iletimerkezi/sdk`](https://github.com/iletimerkezi/iletimerkezi-php)
- **Go:** [`github.com/iletimerkezi/iletimerkezi-go`](https://github.com/iletimerkezi/iletimerkezi-go)
- **Java:** [`iletimerkezi-java`](https://github.com/iletimerkezi/iletimerkezi-java)
- **C# (.NET):** [`iletimerkezi-csharp`](https://github.com/iletimerkezi/iletimerkezi-csharp)
- **Ruby:** [`iletimerkezi-ruby`](https://github.com/iletimerkezi/iletimerkezi-ruby)
- **Laravel:** [`iletimerkezi-laravel`](https://github.com/iletimerkezi/iletimerkezi-laravel)

SDK API surfaces vary slightly across languages (e.g., Node `add(string | string[])` vs PHP `create(string)`); see the per-endpoint notes on each page.

## Turkey-specific concerns

- **IYS compliance:** before sending commercial messages, you must register consent in the Turkish messaging consent registry (İYS). `send-sms` requires `iys: "1"` + `iysList: "BIREYSEL"` (individual) or `"TACIR"` (business). See [send-sms](./send-sms.md).
- **11-character sender limit:** sender IDs are max 11 alphanumeric characters; no Turkish characters allowed.
- **Number format:** `905XXXXXXXXX`, `+905XXXXXXXXX`, and `5XXXXXXXXX` are all accepted; responses come back with a `+90` prefix.
- **B186 operator code and character limits:** by a Turkish telecom regulator decision (BTK, ruling 2016/DK-YED/211 dated 12.04.2016), iletiMerkezi automatically appends `B186` to the end of every SMS. As a result the real character limits are slightly lower than the standard SMS values:

  | Character set | First SMS | Subsequent parts |
  |---|---|---|
  | English (GSM-7) | 155 | 153 |
  | Turkish | 150 | 148 |
  | Unicode (UCS-2, emoji, etc.) | 65 | 63 |

  Messages over the limit are sent as multi-part SMS automatically; each part consumes one credit. Turkish characters (`ş, ğ, ı, ç, ö, ü, İ, Ş, Ğ, Ç, Ö, Ü`) keep the message in Turkish mode; introducing emoji or other Unicode characters drops it to UCS-2 (65/63). The character mode can also be selected from your panel settings.

- **Up to 7-part long SMS:** a single message in one order is concatenated up to 7 parts maximum, which corresponds to roughly **1071 characters** (GSM-7 mode). Longer messages are not accepted — shorten the body or split the content with an [iim.to short link](https://www.iletimerkezi.com/kisa-link).

- **Undelivered SMS are free:** messages that don't reach the recipient (off network, invalid number, blacklist, etc.) do not consume credit; the refund is reflected on your panel account. Read actual consumption from [`get-report`](./get-report.md) — the `delivered` counter and `price` field.

- **International (abroad) SMS mode:** to send to numbers outside Turkey, enable abroad mode from the panel under **Settings → SMS → Abroad**. Activation converts your existing SMS credits to a TL balance (the account moves from credit-count billing to TL-balance billing). After that, `send-sms` accepts recipient numbers with international country codes (e.g., `+49`, `+44`).

- **IP restriction (optional security):** from the panel under **Settings → Security → Static IP**, the panel and API can be locked down to separate whitelists (5 IPs each). When active, requests from any other IP are rejected with `401`. A static IP is required for production; a dynamic IP gets cut off whenever the modem restarts.

## Status and support

- API status: production status is announced from the iletiMerkezi panel.
- Spotted a doc/API mismatch? Open an issue at [`iletimerkezi/apidocs-website`](https://github.com/iletimerkezi/apidocs-website/issues). The live API is the ground truth.
- Extra support: `destek@emarka.com.tr`.

## Related

- [Authentication](./authentication.md)
- [Send SMS (send-sms)](./send-sms.md)
- [Testing and development (test-mode)](./test-mode.md)
- [Error code table (error-codes)](./error-codes.md)