--- 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-05-05 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 | | [cancel-order](./cancel-order.md) | `POST /v1/cancel-order/json` | Cancel a future-scheduled order before dispatch | | [get-report](./get-report.md) | `POST /v1/get-report/json` | Single-order delivery report (summary + per-recipient) | | [get-reports](./get-reports.md) | `POST /v1/get-reports/json` | Order summary list within a date range (no per-recipient detail) | | [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 | | [iys-register](./iys-register.md) | `POST /v1/consent/create/json` | İYS consent register (batch, 1-5000 per request) | | [iys-check](./iys-check.md) | `POST /v1/consent/show/json` | İYS consent query (single recipient) | | [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`; message text may evolve over time, but 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 limits The [`send-sms`](./send-sms.md) endpoint has two distinct limits: - **Transactional sending:** up to **100 SMS per second** per account. Typical use: OTP, login codes, order/delivery notifications, appointment reminders, per-user triggered, single-recipient messages. - **Bulk sending:** up to **50,000 recipients in a single request** (`order.message.receipents.number` array). Typical use: campaigns, broadcasts, mass alerts. One order is tracked under one `orderId`. Practical rules: - For recipient lists over 50,000, chunk client-side at `chunkSize=50000` and issue sequential [`send-sms`](./send-sms.md) calls; each call returns its own `orderId`. - For sustained throughput above 100 transactional SMS per second, plan ahead with `destek@emarka.com.tr` so dedicated capacity can be provisioned. - Use exponential backoff in production error paths; abnormal traffic may be temporarily throttled to protect overall service health. - For bulk delivery, prefer a single request with multiple recipients over many sequential single-recipient calls. It is faster and easier on the platform. Other endpoints (reports, balance, blacklist, İYS check) have no published hard request limit and run on a fair-use basis. Idempotency behavior for side-effecting endpoints such as `add-blacklist` and `send-sms` is documented on each endpoint page. ## SDKs Official SDKs published to package registries: - **Node.js / TypeScript:** npm `@iletimerkezi/iletimerkezi-node` ([npm](https://www.npmjs.com/package/@iletimerkezi/iletimerkezi-node), [GitHub](https://github.com/iletimerkezi/iletimerkezi-node)) - **PHP:** Packagist `iletimerkezi/iletimerkezi-php` ([Packagist](https://packagist.org/packages/iletimerkezi/iletimerkezi-php), [GitHub](https://github.com/iletimerkezi/iletimerkezi-php)) Source code for other languages (Python, Go, Java, C#, Ruby, Laravel) is available on GitHub but not yet published to package registries, call the REST API directly or contact `destek@emarka.com.tr` for help. For LLM-based development workflows: the **MCP server** (`@iletimerkezi/mcp-server`) lets Claude Code, Cursor, Gemini CLI and similar clients drive the 11 SMS tools from a single conversation. See [/en/docs/mcp](/en/docs/mcp). ## 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. **The character mode is configured at the account level from the panel.** The default mode is **English (GSM-7)**; to send Turkish characters or Unicode (emoji, other alphabets) you must first enable the corresponding Universal Language Support mode in the panel: [`panel.iletimerkezi.com/settings/sms/encoding`](https://panel.iletimerkezi.com/settings/sms/encoding). Without this setting, Turkish or Unicode characters are converted (e.g. `ş > s`, emoji stripped). Once enabled, the message body is placed automatically into the matching mode: Turkish-only characters > Turkish mode (150/148), emoji or other Unicode > UCS-2 (65/63). - **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)