# TurkeySMS API v4 · OpenAPI 3.1 · generated from the TASK-105 docs content (CONTRACT_FINAL.md). Do not edit by hand. openapi: 3.1.0 info: title: TurkeySMS API version: 4.0.0 description: |- With the TurkeySMS API you can send SMS and OTP messages from your application, schedule sends, manage your contacts, query your balance and Sender IDs, and retrieve send reports. All requests are sent over HTTPS with the `POST` method, and responses are in JSON. The information in this specification is based on how the API behaves in the live system. | Section | Endpoints | |---|---| | [Key check](https://api.turkeysms.com.tr/documentation/english#anahtar-denetimi) | `/auth/post/check/` | | [Messaging](https://api.turkeysms.com.tr/documentation/english#sms-gonderimi) | `/sms/send`, `/group/send`, `/group/sendMixed`, `/otp/send`, `/otp/detailed` | | [Contacts](https://api.turkeysms.com.tr/documentation/english#gruplar) | `/groups/create`, `/groups/edit`, `/groups/delete`, `/groups/list`, `/contacts/add`, `/blacklist/post/add`, `/blacklist/post/status` | | [Queries and reports](https://api.turkeysms.com.tr/documentation/english#bakiye-sorgu) | `/balance/`, `/senderid/check`, `/sms/status`, `/reports/basic`, `/reports/detailed` | | [Webhook](https://api.turkeysms.com.tr/documentation/english#webhooks) | Event notifications are sent to your server | ## General rules #### Base URL and request format - Base URL: `https://api.turkeysms.com.tr`. Endpoint paths are appended to this URL (for example, `https://api.turkeysms.com.tr/sms/send`). The URL has no version prefix. - All endpoints accept `POST` only. - Send the body as JSON (`Content-Type: application/json`, UTF-8). Form data is also accepted; the examples use JSON. The query string is not read. - Use the paths exactly as written on this page. `/balance/` and `/auth/post/check/` are written with a trailing slash; `/senderid/check` and the others are written without one. A wrong path returns a redirect (301) or 404. #### Authentication Send your API key in the `api_key` field of the body with every request. A key sent in an HTTP header (for example, `Authorization`) is not read. > **Warning:** Use the API key on the server side only. Do not put it in code that runs in the browser, in a mobile app package or in a public repository. If you think the key has been exposed, rotate or revoke it in the panel (see [API keys](https://api.turkeysms.com.tr/documentation/english#api-anahtarlari)). #### Response format Most endpoints use the envelope below. In successful responses, endpoint-specific fields are added to the same object. ```json { "result": false, "result_code": "TS-1031", "result_message": "Invalid API key. Authentication failed." } ``` The [Reports](https://api.turkeysms.com.tr/documentation/english#raporlar) and [Number blocking](https://api.turkeysms.com.tr/documentation/english#numara-engelleme) endpoints use the `status` field (`"success"` or `"error"`) instead of `result`. > **Note:** **Evaluate the result from the body, not from the HTTP code.** Some endpoints return a failed result with HTTP 200 (for example, when a group name already exists or a report is not found). Check the `result` (or `status`) and `result_code` fields. `result_message` texts are in English and may change; use `result_code` in your program. On an unexpected server error, the response is usually HTTP 500 with `result_code` `SRV-ERR` (`TS-5000` in Key check). Rarely, the response may not be JSON, or may contain an `error` field instead of `result_code`; also catch JSON parsing errors in your code. You can retry the request after a short while; on send endpoints, before retrying, check whether the message went out with [SMS status query](https://api.turkeysms.com.tr/documentation/english#sms-durumu-sorgu) or [Reports](https://api.turkeysms.com.tr/documentation/english#raporlar). #### Rate limit A per-minute send limit may apply to `/sms/send` at the account level. This limit is set on your account by TurkeySMS. The limit counts the messages (recipients) recorded from your account in the last minute, not the number of requests. When the limit is reached, the response is HTTP 429 with `TS-1060`; wait a while and retry. > **Note:** This limit is separate from the hourly, daily and monthly limits you can set for a key in the API Center (see [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler)). #### Date and time Dates use the `YYYY-MM-DD` format, and times use `HH:MM:SS` (hour:minute:second) or, in some fields, `HH:MM`. Date and time values returned in responses carry no time zone information. ## Message language and SMS count `sms_lang` (`lang` in Advanced OTP) sets the message's character set and how many SMS it counts as. A wrong value can cause the text to be split into more SMS. | Value | Use | |---|---| | `0` | English; Latin letters and standard symbols only (no Turkish characters). | | `1` | Turkish; text that contains ç, ğ, ı, İ, ö, ş, ü. | | `2` | Arabic and other Unicode text. This is the default value. | #### SMS count The numbers in the table are the maximum number of characters that fit in the given SMS count. The character count is calculated after `TS-L` is converted to a line break. | Text length up to | 1 | 2 | 3 | 4 | 5 | 6 | 7 | |---|---|---|---|---|---|---|---| | **Türkiye numbers**, `sms_lang` 0 | 160 | 305 | 455 | 610 | 760 | 910 | 1070 | | **Türkiye numbers**, `sms_lang` 1 | 155 | 245 | 445 | 595 | 740 | 890 | 1040 | | **Türkiye numbers**, `sms_lang` 2 | 65 | 127 | 190 | 250 | 315 | 380 | 445 | | **International numbers** (all values) | 70 | 130 | 195 | 260 | 325 | 390 | 450 | - Texts longer than the last column count as 8 SMS. - `/sms/send` and `/otp/detailed` treat numbers that do not start with `905` as international numbers. `/group/send` and `/group/sendMixed` use the Türkiye table for all numbers. #### Content label `content_type` in a `/sms/send` request (`0` Transactional, `1` High Quality, `2` Advertising) is returned only as a label in the response; it does not change the sending route or the price. ## Trying requests from this page > **Warning:** Requests sent from this page go to the live system; on send endpoints, real SMS messages are sent. “Try it out” is off by default: open an endpoint and press “Try it out” to send a request. There is no “Authorize” step: put your `api_key` in the request body. Full documentation: [English](https://api.turkeysms.com.tr/documentation/english) · [Türkçe](https://api.turkeysms.com.tr/documentation/turkce) · [العربية](https://api.turkeysms.com.tr/documentation/arabic). Webhook events are described in the [Webhook section](https://api.turkeysms.com.tr/documentation/english#webhooks). contact: name: TurkeySMS Support email: support@turkeysms.com.tr url: http://help.turkeysms.com.tr servers: - url: https://api.turkeysms.com.tr description: Production (live) tags: - name: API keys description: See [API keys](https://api.turkeysms.com.tr/documentation/english#api-anahtarlari). - name: Messaging - name: Contacts - name: Queries and reports paths: /auth/post/check/: post: tags: - API keys operationId: authCheck summary: Key check description: |- **Required permission:** None. An active API key is enough. Returns whether your API key is valid, its permissions and an account summary. You can use it to check the permissions before taking an integration live. > **Note:** The URL is written with a trailing slash: `/auth/post/check/`. The old `/auth/check` URL is not used (404). **Panel equivalents of the permission fields:** | Field | Panel permission | |---|---| | `post_request` | Allow POST requests | | `send_single_sms` | Send SMS | | `send_group_sms` | Send to group | | `send_otp` | Send OTP | | `send_otp_advanced` | Advanced OTP | | `create_group` | Create group | | `manage_groups` | Create group (old name; carries the same value as `create_group` and is kept for backward compatibility) | | `edit_group` | Edit group | | `delete_group` | Delete group | | `list_groups` | List groups | | `add_contact` | Add number | | `delete_contact` | Has no equivalent in the panel; not used by the endpoints documented on this page. | | `block_number` | Block number | | `check_balance` | Check balance | | `check_sms_status` | Check SMS status | | `check_senderid` | Check Sender ID | Full documentation: [Key check](https://api.turkeysms.com.tr/documentation/english#anahtar-denetimi) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. 20–128 characters. required: - api_key examples: example: summary: Example value: api_key: API_ANAHTARINIZ responses: '200': description: |- OK: - `TS-1000`: The key is valid; permissions and the account summary were returned. content: application/json: schema: $ref: '#/components/schemas/AuthCheckResponse' examples: ts_1000_200_ok: summary: 200 OK value: result: true result_code: TS-1000 result_message: Authentication audit successful key_details: status: Active permissions: post_request: true send_single_sms: true send_otp: true check_balance: true check_senderid: true manage_groups: false send_group_sms: true send_otp_advanced: false create_group: false edit_group: false delete_group: false list_groups: false add_contact: false delete_contact: false block_number: false check_sms_status: true account_summary: account_status: Active balance: main: 1500 international: 0 global_sending: false audit_info: request_ip: 203.0.113.10 checked_at: '2026-10-01 14:30:00' '400': description: |- Bad request: - `TS-1031`: The key was not found or is not in the “Active” state. - `TS-1030`: The account is not active. content: application/json: schema: $ref: '#/components/schemas/ResultError' examples: ts_1031_400: summary: '400' value: result: false result_code: TS-1031 result_message: Invalid API key '401': description: |- Unauthorized: - `TS-1031`: `api_key` is missing, is not a string or is outside 20–128 characters. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `TS-5000`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /sms/send: post: tags: - Messaging operationId: smsSend summary: Sending SMS (immediate or scheduled) description: |- **Required permissions:** “Allow POST requests” and “Send SMS” (API Center → My Keys → key → Scopes) Sends the same text to one or more numbers. When the request succeeds, the messages are accepted for delivery to the operator. #### Number format Send numbers in international format, without a leading `+`: `905XXXXXXXXX`. The API removes spaces, `+`, `-` and parentheses; removes the `00` from numbers that start with `00`; and converts `05…` and 10-digit `5…` numbers to the `905…` format. Numbers are not validated one by one; a wrong number is also accepted and added to the SMS count. Validate numbers on your side before sending. #### Rules - Your balance must cover the total SMS count calculated for all recipients; if it does not, no message is sent (`TS-1027`). - The per-minute send limit applies to this endpoint (see [Rate limit](https://api.turkeysms.com.tr/documentation/english#hiz-siniri)). - Your number blocking list is not applied on this endpoint (see [Number blocking](https://api.turkeysms.com.tr/documentation/english#numara-engelleme)). #### Notes - If you have set up a webhook, the `sms.sent`, `sms.delivered` and `sms.failed` events are sent for this send. For which webhook an event goes to, see [Webhook → Routing](https://api.turkeysms.com.tr/documentation/english#wh-routing). - Before resending a request because of a timeout, check whether the first request was processed; otherwise the message may be sent twice. #### Scheduled sending - The specified time must be in the future. The date and time are evaluated in Türkiye time (Europe/Istanbul). - At most **50,000** distinct numbers can be sent in one request. - The balance check and the per-minute send limit are applied at the time of the request. For a scheduled send, `sms_id` is the send's **report ID**. Use this value as `raporid` in the [Reports](https://api.turkeysms.com.tr/documentation/english#raporlar) endpoints; [SMS status query](https://api.turkeysms.com.tr/documentation/english#sms-durumu-sorgu) does not recognize this ID. Full documentation: [Sending SMS (immediate or scheduled)](https://api.turkeysms.com.tr/documentation/english#sms-gonderimi) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. sentto: type: string description: Recipient number. Separate multiple numbers with commas, semicolons or line breaks. At most **500** distinct numbers per request (50,000 for scheduled sends). If a number appears more than once, it receives the message once. title: type: string description: A Sender ID approved on your account. At most 11 characters; Turkish characters (ç, ğ, ı, ö, ş, ü) count as two characters. text: type: string description: Message text. At most 2,000 characters. The `TS-L` token in the text is converted to a line break. sms_lang: type: integer description: 'Character set and SMS count calculation: `0` English, `1` Turkish, `2` Arabic/Unicode. Default `2`. For Turkish text, send `1` (see [Message language and SMS count](https://api.turkeysms.com.tr/documentation/english#mesaj-dili)).' content_type: type: integer description: 'Content label: `0` Transactional, `1` High Quality, `2` Advertising. Default `0`. Returned only as a label in the response; it does not affect the send.' scheduled_date: type: string description: If set, the send is scheduled. See [Scheduled sending](https://api.turkeysms.com.tr/documentation/english#zamanlanmis-gonderim). Send date, `YYYY-MM-DD` (for example, `2026-10-15`). scheduled_time: type: string description: Conditional. Required when `scheduled_date` is sent. Send time, `HH:MM` or `HH:MM:ss` (for example, `09:30`). required: - api_key - sentto - title - text examples: example: summary: Example value: api_key: API_ANAHTARINIZ title: BASLIGINIZ sentto: 905XXXXXXXXX,905YYYYYYYYY text: Randevunuz yarın 10:00'da.TS-LBilgi için bizi arayın. sms_lang: 1 scheduled: summary: Scheduled sending value: api_key: API_ANAHTARINIZ title: BASLIGINIZ sentto: 905XXXXXXXXX text: Kampanyamız yarın başlıyor. sms_lang: 1 scheduled_date: '2026-10-15' scheduled_time: 09:30 responses: '200': description: |- OK: - `TS-1024`: The send was accepted. content: application/json: schema: $ref: '#/components/schemas/SmsSendResponse' examples: ts_1024_200_ok: summary: 200 OK value: result: true result_code: TS-1024 result_message: SMS dispatched successfully. sms_id: 48213377 number_of_sms: 2 total_recipients: 2 success_count: 2 sms_lang: Turkish content_type: Transactional country: Turkey-TR ts_1024_200_ok_scheduled: summary: 200 OK (scheduled) value: result: true result_code: TS-1024 result_message: SMS dispatched successfully. sms_id: 734129955 number_of_sms: 1 total_recipients: 1 success_count: 1 sms_lang: Turkish content_type: Transactional country: Turkey-TR '400': description: |- Bad request: - `TS-1033`: The body is not valid JSON or form data. - `TS-1025`: `sentto` is missing, shorter than 7 characters or contains no number. - `TS-1051`: `title` is missing. - `TS-1029`: `title` is longer than 11 characters. - `TS-1026`: `text` is empty or longer than 2,000 characters. - `TS-1060`: The recipient limit was exceeded: 500 (50,000 for scheduled sends). - `TS-1028`: The Sender ID was not found on your account or is not approved. - `TS-1070`: `scheduled_date` is not in `YYYY-MM-DD` format or `scheduled_time` is missing. - `TS-1071`: `scheduled_time` is not in `HH:MM` or `HH:MM:ss` format. - `TS-1072`: The specified time is in the past or invalid (for example, `25:99`). content: application/json: schema: $ref: '#/components/schemas/ResultError' examples: ts_1072_400_scheduled: summary: 400 (scheduled) value: result: false result_code: TS-1072 result_message: Scheduled time must not be in the past. '401': description: |- Unauthorized: - `TS-1050`: `api_key` is missing or shorter than 30 characters. - `TS-1031`: The key was not found or is not active. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1061`: The “Allow POST requests” permission is off. - `TS-1062`: The “Send SMS” permission is off. - `TS-1030`: The account is not active. - `TS-1027`: Insufficient balance. - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' examples: ts_1027_403: summary: '403' value: result: false result_code: TS-1027 result_message: Insufficient SMS credits. Please top up your account. '429': description: |- Too many requests: - `TS-1060`: The per-minute send limit was exceeded. - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /group/send: post: tags: - Messaging operationId: groupSend summary: 'Group sending: same text' description: |- **Required permission:** “Send to group” (API Center → My Keys → key → Scopes) Sends to many numbers with a single request. There are two endpoints: - `/group/send`: the **same** text to all numbers. - `/group/sendMixed`: each number gets **its own** text. `text` is an array whose order matches the number array. #### Rules - Numbers are converted with the same rules as `/sms/send`: spaces, `+`, `-` and parentheses are removed; the `00` is removed from numbers that start with `00`; and `05…` and 10-digit `5…` numbers are converted to the `905…` format. Numbers are not validated one by one. - In a `/group/send` request, a repeated number is queued once. In a `/group/sendMixed` request, an identical number and text pair is queued once; different texts to the same number are sent separately. - Your balance must cover the total SMS count (`TS-1027`). - Send the date and time fields only together with `scheduled_sms: 1`. - Your number blocking list is not applied on these endpoints (see [Number blocking](https://api.turkeysms.com.tr/documentation/english#numara-engelleme)). - A successful response shows that the send has been queued; the messages are sent afterwards. Full documentation: [Group sending: same text](https://api.turkeysms.com.tr/documentation/english#grup-gonderimi) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. title: type: string description: A Sender ID approved on your account. sentto: type: array items: type: string description: An array of numbers (a JSON array; comma-separated text is not accepted). At most **50,000** items. It can also be sent as `numbers`. text: type: string description: '`/group/send`: a single text. `/group/sendMixed`: an array of texts with the same length as the number array; `text[i]` goes to the number `sentto[i]`. Each text is at most 2,000 characters; `TS-L` is converted to a line break.' sms_lang: type: integer description: '`0` English, `1` Turkish, `2` Arabic/Unicode. Default `2`. For Turkish text, send `1`.' scheduled_sms: type: integer description: If `1` is sent, the send is scheduled. scheduled_date: type: string description: Conditional. Required if `scheduled_sms` is `1`. `YYYY-MM-DD`. scheduled_time: type: string description: Conditional. Required if `scheduled_sms` is `1`. `HH:MM` or `HH:MM:ss`. The date and time are evaluated in Türkiye time (Europe/Istanbul). required: - api_key - title - sentto - text examples: example: summary: Example value: api_key: API_ANAHTARINIZ title: BASLIGINIZ sentto: - 905XXXXXXXXX - 905YYYYYYYYY text: Mağazamız bugün 21:00'e kadar açıktır. sms_lang: 1 responses: '200': description: |- OK: - `TS-1024`: The send was accepted. content: application/json: schema: $ref: '#/components/schemas/GroupSendResponse' examples: ts_1024_200_ok: summary: 200 OK value: result: true result_code: TS-1024 result_message: Bulk SMS dispatched successfully. rapor_id: 482913377 total_numbers: 2 total_sms_cost: 2 scheduled: false '400': description: |- Bad request: - `TS-1033`: The body is invalid, `text` is empty, `text` has the wrong type, or in `/group/sendMixed` the number of texts and numbers is not equal. - `TS-1025`: `api_key` is missing or shorter than 30 characters. - `TS-1029`: `title` is missing. - `TS-1026`: `sentto` is missing or not an array, or a text is longer than 2,000 characters. - `TS-1060`: The 50,000 number limit was exceeded. - `TS-1070 / TS-1071 / TS-1072`: The scheduling fields are invalid: date format, time format or a time in the past. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1031`: The key was not found or is not active. - `TS-1067`: The “Send to group” permission is off. - `TS-1030`: The account is not active. - `TS-1028`: The Sender ID was not found on your account or is not approved. - `TS-1027`: Insufficient balance. - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' examples: ts_1028_403: summary: '403' value: result: false result_code: TS-1028 result_message: Sender ID was not found in your account or is not approved. '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /group/sendMixed: post: tags: - Messaging operationId: groupSendMixed summary: 'Group sending: one text per number' description: |- **Required permission:** “Send to group” (API Center → My Keys → key → Scopes) Sends to many numbers with a single request. There are two endpoints: - `/group/send`: the **same** text to all numbers. - `/group/sendMixed`: each number gets **its own** text. `text` is an array whose order matches the number array. #### Rules - Numbers are converted with the same rules as `/sms/send`: spaces, `+`, `-` and parentheses are removed; the `00` is removed from numbers that start with `00`; and `05…` and 10-digit `5…` numbers are converted to the `905…` format. Numbers are not validated one by one. - In a `/group/send` request, a repeated number is queued once. In a `/group/sendMixed` request, an identical number and text pair is queued once; different texts to the same number are sent separately. - Your balance must cover the total SMS count (`TS-1027`). - Send the date and time fields only together with `scheduled_sms: 1`. - Your number blocking list is not applied on these endpoints (see [Number blocking](https://api.turkeysms.com.tr/documentation/english#numara-engelleme)). - A successful response shows that the send has been queued; the messages are sent afterwards. Full documentation: [Group sending: one text per number](https://api.turkeysms.com.tr/documentation/english#grup-gonderimi) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. title: type: string description: A Sender ID approved on your account. sentto: type: array items: type: string description: An array of numbers (a JSON array; comma-separated text is not accepted). At most **50,000** items. It can also be sent as `numbers`. text: type: array items: type: string description: '`/group/send`: a single text. `/group/sendMixed`: an array of texts with the same length as the number array; `text[i]` goes to the number `sentto[i]`. Each text is at most 2,000 characters; `TS-L` is converted to a line break.' sms_lang: type: integer description: '`0` English, `1` Turkish, `2` Arabic/Unicode. Default `2`. For Turkish text, send `1`.' scheduled_sms: type: integer description: If `1` is sent, the send is scheduled. scheduled_date: type: string description: Conditional. Required if `scheduled_sms` is `1`. `YYYY-MM-DD`. scheduled_time: type: string description: Conditional. Required if `scheduled_sms` is `1`. `HH:MM` or `HH:MM:ss`. The date and time are evaluated in Türkiye time (Europe/Istanbul). required: - api_key - title - sentto - text examples: example: summary: Example value: api_key: API_ANAHTARINIZ title: BASLIGINIZ sentto: - 905XXXXXXXXX - 905YYYYYYYYY text: - Sayın Ayşe Hanım, siparişiniz hazır. - Sayın Mehmet Bey, siparişiniz hazır. sms_lang: 1 responses: '200': description: |- OK: - `TS-1024`: The send was accepted. content: application/json: schema: $ref: '#/components/schemas/GroupSendMixedResponse' examples: ts_1024_200_ok: summary: 200 OK value: result: true result_code: TS-1024 result_message: Bulk SMS dispatched successfully. rapor_id: 482913377 total_numbers: 2 total_sms_cost: 2 scheduled: false '400': description: |- Bad request: - `TS-1033`: The body is invalid, `text` is empty, `text` has the wrong type, or in `/group/sendMixed` the number of texts and numbers is not equal. - `TS-1025`: `api_key` is missing or shorter than 30 characters. - `TS-1029`: `title` is missing. - `TS-1026`: `sentto` is missing or not an array, or a text is longer than 2,000 characters. - `TS-1060`: The 50,000 number limit was exceeded. - `TS-1070 / TS-1071 / TS-1072`: The scheduling fields are invalid: date format, time format or a time in the past. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1031`: The key was not found or is not active. - `TS-1067`: The “Send to group” permission is off. - `TS-1030`: The account is not active. - `TS-1028`: The Sender ID was not found on your account or is not approved. - `TS-1027`: Insufficient balance. - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' examples: ts_1028_403: summary: '403' value: result: false result_code: TS-1028 result_message: Sender ID was not found in your account or is not approved. '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /otp/send: post: tags: - Messaging operationId: otpSend summary: Sending OTP description: |- **Required permission:** “Send OTP” (API Center → My Keys → key → Scopes) Sends a verification code (OTP) generated by TurkeySMS to a single number. The text comes from a fixed template; the sender name is always `OTPSMS`. #### Templates `MARKA` is the OTP brand name set on your account. In the example, the code is `4821`. `sms_lang: 1 (Turkish)`: ``` 4821 Aktivasyon kodunuz OTP MARKA ``` `sms_lang: 0 (English)`: ``` Your activation code is:4821 MARKA ``` `sms_lang: 2 (Arabic)`: ``` 4821 هو رمز التفعيل الخاص بك MARKA ``` > **Warning:** **Verifying the code is your system's job.** The API has no verification endpoint. Store the `otp_code` value on your server with a short validity period (for example, 3–5 minutes), compare it with the code the user enters, and delete it after use. Do not send the code to the client (browser, mobile app). On your side, limit how many requests can be made to the same number within a short time. Full documentation: [Sending OTP](https://api.turkeysms.com.tr/documentation/english#otp-gonderimi) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. mobile: type: string description: A single recipient number. Send it in the `905XXXXXXXXX` format; the `05…`, `5…` and `00…` formats are also converted. digits: type: integer description: 'Code length: `4`, `5` or `6`. Default `4`; for any other value, `4` is used.' sms_lang: type: integer description: 'Template language: `0` English, `1` Turkish, `2` Arabic. Default `2`. It can also be sent as `lang`; if both are sent, `sms_lang` is used.' required: - api_key - mobile examples: example: summary: Example value: api_key: API_ANAHTARINIZ mobile: 905XXXXXXXXX digits: 6 sms_lang: 1 responses: '200': description: |- OK: - `TS-1024`: The send was accepted. content: application/json: schema: $ref: '#/components/schemas/OtpSendResponse' examples: ts_1024_200_ok: summary: 200 OK value: result: true result_code: TS-1024 result_message: OTP dispatched successfully. sms_id: 48213390 otp_code: 482193 sandbox: false '400': description: |- Bad request: - `TS-1033`: The body is invalid. - `TS-1025`: `mobile` is missing or shorter than 7 characters. content: application/json: schema: $ref: '#/components/schemas/ResultError' '401': description: |- Unauthorized: - `TS-1050`: `api_key` is missing or shorter than 30 characters. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1034`: The number format is invalid (it must be 11–15 digits after cleanup). - `TS-1031`: The key was not found or is not active. - `TS-1036`: The “Send OTP” permission is off. - `TS-1030`: The account is not active. - `TS-1027`: Insufficient balance. - `TS-5000`: The message could not be saved; retry the request. - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' examples: ts_1036_403: summary: '403' value: result: false result_code: TS-1036 result_message: OTP sending privilege is disabled for this API key. '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /otp/detailed: post: tags: - Messaging operationId: otpDetailed summary: Advanced OTP description: |- **Required permissions:** “Allow POST requests” and “Advanced OTP” (API Center → My Keys → key → Scopes) Sends an OTP with your own Sender ID and your own text. TurkeySMS generates the code and puts it in place of the `TS-CODE` token in the text. #### Rules - The following Sender IDs are not accepted (case-insensitive): `test`, `api`, `apikey`, `api_key`, `test123`, `123`, `0000`, `123456789`, `senderid`, `sender`, `title`, `text`, `content`. - Your balance must cover the SMS count of the text. The SMS count is calculated with the tables in [Message language and SMS count](https://api.turkeysms.com.tr/documentation/english#mesaj-dili). - Validation errors are returned with HTTP 400, and account and permission errors with HTTP 403. > **Note:** If an error occurs during delivery to the operator, the response is still `TS-1024`. You can check the message status with [SMS status query](https://api.turkeysms.com.tr/documentation/english#sms-durumu-sorgu); on a delivery error it returns `TS-1022` with the error description in the `details` field. The warning about verifying the code in [Sending OTP](https://api.turkeysms.com.tr/documentation/english#otp-gonderimi) also applies here. Full documentation: [Advanced OTP](https://api.turkeysms.com.tr/documentation/english#gelismis-otp) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. mobile: type: string description: A single recipient number, `905XXXXXXXXX`. title: type: string description: A Sender ID on your account. At most 11 characters; Turkish characters count as two characters. The Sender ID must be approved, its document must be approved and the operator approval must be complete. text: type: string description: Message text; it must contain the `TS-CODE` token (in capitals). At most 2,000 characters. `TS-L` is converted to a line break. lang: type: integer description: '`0` English, `1` Turkish, `2` Arabic/Unicode. Default `2`. This endpoint does not read `sms_lang`; use `lang`.' digits: type: integer description: 'Code length: `4`, `5` or `6`. Default `4`.' required: - api_key - mobile - title - text examples: example: summary: Example value: api_key: API_ANAHTARINIZ mobile: 905XXXXXXXXX title: BASLIGINIZ text: 'Giriş kodunuz: TS-CODE. Kodu kimseyle paylaşmayın.' lang: 1 digits: 6 responses: '200': description: |- OK: - `TS-1024`: The send was accepted. content: application/json: schema: $ref: '#/components/schemas/OtpDetailedResponse' examples: ts_1024_200_ok: summary: 200 OK value: result: true result_code: TS-1024 result_message: OTP dispatched successfully. sms_id: 48213391 otp_code: 482193 number_of_sms: 1 sms_lang: Turkish sandbox: false '400': description: |- Bad request: - `TS-1033`: The body is invalid, a field is not a string, or the Sender ID is on the not-accepted list. - `TS-1050`: `api_key` is missing. - `TS-1025`: `mobile` is missing. - `TS-1051`: `title` is missing. - `TS-1026`: `text` is empty, does not contain `TS-CODE` or is longer than 2,000 characters. - `TS-1031`: 400: the key is shorter than 30 characters. 403: the key was not found or is not active. - `TS-1034`: The number format is invalid. - `TS-1029`: 400: the Sender ID is longer than 11 characters. 403: the Sender ID was not found on your account. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1031`: 400: the key is shorter than 30 characters. 403: the key was not found or is not active. - `TS-1029`: 400: the Sender ID is longer than 11 characters. 403: the Sender ID was not found on your account. - `TS-1061`: The “Allow POST requests” permission is off. - `TS-1037`: The “Advanced OTP” permission is off. - `TS-1030`: The account is not active. - `TS-1028`: The Sender ID is not approved for OTP (approval, document or operator approval is missing). - `TS-1027`: Insufficient balance. - `TS-5000`: The message could not be saved; retry the request. - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' examples: ts_1028_403: summary: '403' value: result: false result_code: TS-1028 result_message: Sender ID is not approved for OTP (approval, document and network approval are required). '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /groups/create: post: tags: - Contacts operationId: groupsCreate summary: Creating a group description: |- **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** This endpoint returns some failed results with HTTP 200. **Required permission:** “Create group” (API Center → My Keys → key → Scopes) Creates, renames, deletes and lists the groups in your contacts. Each operation has its own permission. > **Note:** On these endpoints, some failed results are returned with HTTP 200 (for example, `TS-1082`, `TS-1086`). Always evaluate the result with `result` and `result_code`. Use the `group.id` value as `group_id` when adding numbers. Full documentation: [Creating a group](https://api.turkeysms.com.tr/documentation/english#grup-olusturma) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. group_name: type: string description: Group name. 2–50 characters; Turkish characters count as two characters. It must be unique among your active groups. required: - api_key - group_name examples: example: summary: Example value: api_key: API_ANAHTARINIZ group_name: Müşteriler responses: '200': description: |- OK: - `TS-1080`: Created. - `TS-1082`: An active group with this name already exists. **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** Some failed results (`TS-1082`) are returned with HTTP 200. content: application/json: schema: oneOf: - $ref: '#/components/schemas/GroupsCreateResponse' - $ref: '#/components/schemas/ResultError' examples: ts_1080_200_ok: summary: 200 OK value: result: true result_code: TS-1080 result_message: Group created successfully. group: id: 5412 name: Müşteriler created_at: '2026-10-01' ts_1082_200_failed_result: summary: 200 (failed result) value: result: false result_code: TS-1082 result_message: Group name already exists. '400': description: |- Bad request: - `TS-1033`: The body is invalid. - `TS-1050`: `api_key` is missing. - `TS-1031`: The key is shorter than 30 characters, was not found or is not active. - `TS-1081`: The related permission is off: create. - `TS-1030`: The account is not active. - `TS-1083`: The group name is empty or outside 2–50 characters. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /groups/edit: post: tags: - Contacts operationId: groupsEdit summary: Renaming a group description: |- **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** This endpoint returns some failed results with HTTP 200. **Required permission:** “Edit group” (API Center → My Keys → key → Scopes) Creates, renames, deletes and lists the groups in your contacts. Each operation has its own permission. > **Note:** On these endpoints, some failed results are returned with HTTP 200 (for example, `TS-1082`, `TS-1086`). Always evaluate the result with `result` and `result_code`. Full documentation: [Renaming a group](https://api.turkeysms.com.tr/documentation/english#grup-duzenleme) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. group_id: type: integer description: Group ID. new_name: type: string description: New name. This endpoint does not check length or uniqueness; we recommend keeping the name 2–50 characters long and unique. required: - api_key - group_id - new_name examples: example: summary: Example value: api_key: API_ANAHTARINIZ group_id: 5412 new_name: VIP Müşteriler responses: '200': description: |- OK: - `TS-1087`: Updated. - `TS-1083`: The group name is empty or outside 2–50 characters. In edit, it is also returned with 200 for an invalid `group_id`. - `TS-1086`: 400: `group_id` is missing. 200: the group was not found, does not belong to you or has been deleted. **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** Some failed results (`TS-1083`, `TS-1086`) are returned with HTTP 200. content: application/json: schema: oneOf: - $ref: '#/components/schemas/GroupsEditResponse' - $ref: '#/components/schemas/ResultError' examples: ts_1087_200_ok: summary: 200 OK value: result: true result_code: TS-1087 result_message: Group name updated successfully. new_name: VIP Müşteriler '400': description: |- Bad request: - `TS-1033`: The body is invalid. - `TS-1050`: `api_key` is missing. - `TS-1031`: The key is shorter than 30 characters, was not found or is not active. - `TS-1084`: The related permission is off: edit. - `TS-1030`: The account is not active. - `TS-1083`: The group name is empty or outside 2–50 characters. In edit, it is also returned with 200 for an invalid `group_id`. - `TS-1086`: 400: `group_id` is missing. 200: the group was not found, does not belong to you or has been deleted. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /groups/delete: post: tags: - Contacts operationId: groupsDelete summary: Deleting a group description: |- **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** This endpoint returns some failed results with HTTP 200. **Required permission:** “Delete group” (API Center → My Keys → key → Scopes) Creates, renames, deletes and lists the groups in your contacts. Each operation has its own permission. > **Note:** On these endpoints, some failed results are returned with HTTP 200 (for example, `TS-1082`, `TS-1086`). Always evaluate the result with `result` and `result_code`. A deleted group is removed from the lists and cannot be used again. Numbers added to the group are not deleted. Full documentation: [Deleting a group](https://api.turkeysms.com.tr/documentation/english#grup-silme) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. group_id: type: integer description: Group ID. required: - api_key - group_id examples: example: summary: Example value: api_key: API_ANAHTARINIZ group_id: 5412 responses: '200': description: |- OK: - `TS-1088`: Deleted. - `TS-1086`: 400: `group_id` is missing. 200: the group was not found, does not belong to you or has been deleted. **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** Some failed results (`TS-1086`) are returned with HTTP 200. content: application/json: schema: oneOf: - $ref: '#/components/schemas/GroupsDeleteResponse' - $ref: '#/components/schemas/ResultError' examples: ts_1088_200_ok: summary: 200 OK value: result: true result_code: TS-1088 result_message: Group deleted successfully. '400': description: |- Bad request: - `TS-1033`: The body is invalid. - `TS-1050`: `api_key` is missing. - `TS-1031`: The key is shorter than 30 characters, was not found or is not active. - `TS-1085`: The related permission is off: delete. - `TS-1030`: The account is not active. - `TS-1086`: 400: `group_id` is missing. 200: the group was not found, does not belong to you or has been deleted. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /groups/list: post: tags: - Contacts operationId: groupsList summary: Listing groups description: |- **Required permission:** “List groups” (API Center → My Keys → key → Scopes) Creates, renames, deletes and lists the groups in your contacts. Each operation has its own permission. > **Note:** On these endpoints, some failed results are returned with HTTP 200 (for example, `TS-1082`, `TS-1086`). Always evaluate the result with `result` and `result_code`. Only groups that have not been deleted are returned, newest first. There is no pagination. Full documentation: [Listing groups](https://api.turkeysms.com.tr/documentation/english#grup-listeleme) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. search: type: string description: Search within the name. If empty, all groups are returned. required: - api_key examples: example: summary: Example value: api_key: API_ANAHTARINIZ search: Müşteri responses: '200': description: |- OK: - `TS-1090`: Listed. content: application/json: schema: $ref: '#/components/schemas/GroupsListResponse' examples: ts_1090_200_ok: summary: 200 OK value: result: true result_code: TS-1090 result_message: Group list retrieved successfully. groups_count: 2 groups: - id: 5413 name: VIP Müşteriler date: '2026-10-01' - id: 5398 name: Müşteriler 2025 date: '2026-04-02' '400': description: |- Bad request: - `TS-1033`: The body is invalid. - `TS-1050`: `api_key` is missing. - `TS-1031`: The key is shorter than 30 characters, was not found or is not active. - `TS-1089`: The related permission is off: list. - `TS-1030`: The account is not active. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /contacts/add: post: tags: - Contacts operationId: contactsAdd summary: Adding a number to a group description: |- **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** This endpoint returns some failed results with HTTP 200. **Required permission:** “Add number” (API Center → My Keys → key → Scopes) Adds a number to a group. The number is saved to your contacts together with a name and three extra fields. #### Rules - Only Türkiye mobile numbers can be added. - There is no check for whether the same number was already added to the group; prevent duplicates on your side. - Your number blocking list is not checked on this endpoint. `mobile` is the number that was saved. `total_sent`, `total_added` and `total_failed` summarize this single-number operation. Full documentation: [Adding a number to a group](https://api.turkeysms.com.tr/documentation/english#numaralar) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. group_id: type: integer description: The ID of the group the number is added to (see [Groups](https://api.turkeysms.com.tr/documentation/english#gruplar)). gsm_number: type: string description: A Türkiye mobile number. `905XXXXXXXXX`, `05XXXXXXXXX`, `5XXXXXXXXX`, `+905…` and `00905…` are accepted; it is saved as `905XXXXXXXXX`. name: type: string description: The contact's name. f_01: type: string description: Extra fields; free text for personalization. f_02: type: string description: Extra fields; free text for personalization. f_03: type: string description: Extra fields; free text for personalization. required: - api_key - group_id - gsm_number examples: example: summary: Example value: api_key: API_ANAHTARINIZ group_id: 5412 gsm_number: 905XXXXXXXXX name: Ayşe Yılmaz f_01: İstanbul responses: '200': description: |- OK: - `TS-1100`: The number was added. - `TS-1086`: 400: `group_id` is missing, or the group was not found or does not belong to you. 200: `group_id` is not a number or is not greater than zero. - `TS-1101`: The number is not a valid Türkiye mobile number. **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** Some failed results (`TS-1086`, `TS-1101`) are returned with HTTP 200. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ContactsAddResponse' - $ref: '#/components/schemas/ResultError' examples: ts_1100_200_ok: summary: 200 OK value: result: true result_code: TS-1100 result_message: Contact added successfully. group_id: 5412 total_sent: 1 total_added: 1 total_failed: 0 mobile: 905XXXXXXXXX ts_1101_200_failed_result: summary: 200 (failed result) value: result: false result_code: TS-1101 result_message: Failed to add contact. '400': description: |- Bad request: - `TS-1033`: The body is invalid. - `TS-1050`: `api_key` is missing. - `TS-1025`: `gsm_number` is missing. - `TS-1086`: 400: `group_id` is missing, or the group was not found or does not belong to you. 200: `group_id` is not a number or is not greater than zero. - `TS-1031`: The key was not found or is not active. - `TS-1065`: The “Add number” permission is off. - `TS-1030`: The account is not active. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /blacklist/post/add: post: tags: - Contacts operationId: blacklistAdd summary: 'Number blocking: add a number' description: |- **Required permission:** “Block number” (API Center → My Keys → key → Scopes) Adds numbers to your number blocking list and checks whether a number is on the list. The list is per account. > **Warning:** **Scope:** The number blocking list is currently applied only to sends made from the panel. It is not applied to API sends made with `/sms/send`, `/otp/*` and `/group/*`; if you send through the API, filter out blocked numbers on your side. The permission is required for both endpoints. The old `/blacklist/add` and `/blacklist/status` URLs are not used (404). > **Note:** The number is saved in the `905XXXXXXXXX` format, with the same rule as the panel. Adding and querying compare the last 10 digits of the number, so `05321234567` and `905321234567` count as the same number. Landline and foreign numbers are not accepted (`TS-1144`). Response format difference: these endpoints use the `status` field (`"success"` or `"error"`) instead of `result`. Full documentation: [Number blocking: add a number](https://api.turkeysms.com.tr/documentation/english#numara-engelleme) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. number: type: string description: Türkiye mobile number. The `905XXXXXXXXX`, `+90 5XX…`, `0090 5XX…`, `05XX…` and `5XX…` formats are accepted and converted to the `905XXXXXXXXX` format. required: - api_key - number examples: example: summary: Example value: api_key: API_ANAHTARINIZ number: 905XXXXXXXXX responses: '200': description: |- OK: - `TS-1141`: The number was added to the list. content: application/json: schema: $ref: '#/components/schemas/BlacklistAddResponse' examples: ts_1141_200_ok: summary: 200 OK value: status: success result_code: TS-1141 result_message: Number added to blacklist successfully '400': description: |- Bad request: - `TS-1025`: `number` is missing. - `TS-1144`: The number is not a valid Türkiye mobile number. - `TS-1140`: The number is already on your list. - `TS-1033`: An error occurred while saving; retry. content: application/json: schema: $ref: '#/components/schemas/StatusError' '401': description: |- Unauthorized: - `TS-1031`: The key is shorter than 20 characters, was not found or is not active, or the account is not active. content: application/json: schema: $ref: '#/components/schemas/StatusError' '403': description: |- Forbidden: - `TS-1050`: `api_key` is missing or the body is invalid. - `TS-1065`: The “Block number” permission is off. - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/StatusError' '404': description: |- Not found: - `TS-404`: Wrong path. content: application/json: schema: $ref: '#/components/schemas/StatusError' '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/StatusError' /blacklist/post/status: post: tags: - Contacts operationId: blacklistStatus summary: 'Number blocking: check a number' description: |- **Required permission:** “Block number” (API Center → My Keys → key → Scopes) Adds numbers to your number blocking list and checks whether a number is on the list. The list is per account. > **Warning:** **Scope:** The number blocking list is currently applied only to sends made from the panel. It is not applied to API sends made with `/sms/send`, `/otp/*` and `/group/*`; if you send through the API, filter out blocked numbers on your side. The permission is required for both endpoints. The old `/blacklist/add` and `/blacklist/status` URLs are not used (404). > **Note:** The number is saved in the `905XXXXXXXXX` format, with the same rule as the panel. Adding and querying compare the last 10 digits of the number, so `05321234567` and `905321234567` count as the same number. Landline and foreign numbers are not accepted (`TS-1144`). Response format difference: these endpoints use the `status` field (`"success"` or `"error"`) instead of `result`. `block_date` and `block_time` are the date and time the number was added to the list. To view the list and remove numbers, use the **Number Blocking** page in the panel; the API has no remove endpoint. Full documentation: [Number blocking: check a number](https://api.turkeysms.com.tr/documentation/english#numara-engelleme) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. number: type: string description: Türkiye mobile number. The `905XXXXXXXXX`, `+90 5XX…`, `0090 5XX…`, `05XX…` and `5XX…` formats are accepted and converted to the `905XXXXXXXXX` format. required: - api_key - number examples: example: summary: Example value: api_key: API_ANAHTARINIZ number: 905XXXXXXXXX responses: '200': description: |- OK: - `TS-1143 / TS-1142`: The number is on the list / not on the list. content: application/json: schema: $ref: '#/components/schemas/BlacklistStatusResponse' examples: ts_1143_200_ok_on_the_list: summary: 200 OK (on the list) value: status: success result_code: TS-1143 result_message: The phone number is currently in the blacklist. is_blocked: true block_date: '2026-10-01' block_time: '14:30' ts_1142_200_ok_not_on_the_list: summary: 200 OK (not on the list) value: status: success result_code: TS-1142 result_message: The phone number is NOT in the blacklist. is_blocked: false '400': description: |- Bad request: - `TS-1025`: `number` is missing. - `TS-1144`: The number is not a valid Türkiye mobile number. content: application/json: schema: $ref: '#/components/schemas/StatusError' '401': description: |- Unauthorized: - `TS-1031`: The key is shorter than 20 characters, was not found or is not active, or the account is not active. content: application/json: schema: $ref: '#/components/schemas/StatusError' '403': description: |- Forbidden: - `TS-1050`: `api_key` is missing or the body is invalid. - `TS-1065`: The “Block number” permission is off. - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/StatusError' examples: ts_1065_403: summary: '403' value: status: error result_code: TS-1065 result_message: Number blocking privilege is disabled for this API key. '404': description: |- Not found: - `TS-404`: Wrong path. content: application/json: schema: $ref: '#/components/schemas/StatusError' '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/StatusError' /balance/: post: tags: - Queries and reports operationId: balance summary: Balance query description: |- **Required permission:** “Check balance” (API Center → My Keys → key → Scopes) Returns the SMS credit in your account. > **Note:** The URL is written with a trailing slash: `/balance/`. The URL without the slash returns a redirect (301); some HTTP clients turn the `POST` request into `GET` on a redirect, and the request fails. `balance_main`: SMS credit (integer). Full documentation: [Balance query](https://api.turkeysms.com.tr/documentation/english#bakiye-sorgu) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. required: - api_key examples: example: summary: Example value: api_key: API_ANAHTARINIZ responses: '200': description: |- OK: - `TS-1040`: The query succeeded. content: application/json: schema: $ref: '#/components/schemas/BalanceResponse' examples: ts_1040_200_ok: summary: 200 OK value: result: true result_code: TS-1040 result_message: Balance retrieved successfully. balance_main: 1500 '400': description: |- Bad request: - `TS-1033`: The body is invalid. - `TS-1050`: `api_key` is missing. - `TS-1025`: `api_key` is shorter than 30 characters. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1031`: The key was not found or is not active. - `TS-1065`: The “Check balance” permission is off. - `TS-1030`: The account is not active. - `SRV-ERR`: Unexpected server error. - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' examples: ts_1065_403: summary: '403' value: result: false result_code: TS-1065 result_message: Balance inquiry privilege is disabled for this key. '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /senderid/check: post: tags: - Queries and reports operationId: senderidCheck summary: Sender ID query description: |- **Required permission:** “Check Sender ID” (API Center → My Keys → key → Scopes) Lists the Sender IDs approved on your account. In sends, put a Sender ID from this list in the `title` field. The list starts with the newest Sender ID. Sender IDs that are pending approval or rejected are not listed; if there is no approved Sender ID, `sender_ids` is an empty array. Full documentation: [Sender ID query](https://api.turkeysms.com.tr/documentation/english#baslik-sorgu) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. required: - api_key examples: example: summary: Example value: api_key: API_ANAHTARINIZ responses: '200': description: |- OK: - `TS-1040`: The query succeeded. content: application/json: schema: $ref: '#/components/schemas/SenderidCheckResponse' examples: ts_1040_200_ok: summary: 200 OK value: result: true result_code: TS-1040 result_message: Operation success. sender_ids_count: 2 sender_ids: - id: 1288 title: BASLIGINIZ status: 1 network_stat: 1 - id: 1102 title: MAGAZA status: 1 network_stat: 1 '400': description: |- Bad request: - `TS-1033`: The body is invalid. - `TS-1050`: `api_key` is missing. - `TS-1031`: 400: the key is shorter than 30 characters. 403: the key was not found or is not active. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1031`: 400: the key is shorter than 30 characters. 403: the key was not found or is not active. - `TS-1038`: The “Check Sender ID” permission is off. - `TS-1030`: The account is not active. - `SRV-ERR`: Unexpected server error. - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' examples: ts_1038_403: summary: '403' value: result: false result_code: TS-1038 result_message: Sender ID inquiry privilege is disabled for this key. '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /sms/status: post: tags: - Queries and reports operationId: smsStatus summary: SMS status query description: |- **Required permissions:** “Allow POST requests” and “Check SMS status” (API Center → My Keys → key → Scopes) Returns the delivery status of a single message. Only messages sent from your own account can be queried. > **Note:** The IDs of scheduled sends and group sends are report IDs; for these, use the [Reports](https://api.turkeysms.com.tr/documentation/english#raporlar) endpoints. In an immediate send to several recipients, `sms_id` belongs only to the last recipient. Instead of polling the delivery status, we recommend using [Webhook](https://api.turkeysms.com.tr/documentation/english#webhooks). Full documentation: [SMS status query](https://api.turkeysms.com.tr/documentation/english#sms-durumu-sorgu) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. sms_id: type: integer description: 'Message ID: the `sms_id` in the response of an immediate `/sms/send` (single recipient), `/otp/send` or `/otp/detailed`.' required: - api_key - sms_id examples: example: summary: Example value: api_key: API_ANAHTARINIZ sms_id: 48213377 responses: '200': description: |- OK: - `TS-1064`: The message was delivered. - `TS-1022`: No delivery confirmation (not delivered or the report has not arrived yet). content: application/json: schema: $ref: '#/components/schemas/SmsStatusResponse' examples: ts_1064_200_ok: summary: 200 OK value: result: true result_code: TS-1064 result_message: Number received the message. sender_id: BASLIGINIZ date_of_sending: '2026-10-01' time_of_sending: '14:27:12' sms_status: Number received the message sms_balance: 1 SMS details: OK operator: Turkcell '400': description: |- Bad request: - `TS-1033`: The body is invalid. content: application/json: schema: $ref: '#/components/schemas/ResultError' '403': description: |- Forbidden: - `TS-1050`: `api_key` is missing. - `TS-1052`: `sms_id` is missing, is not a number or is not greater than zero. - `TS-1031`: The key was not found or is not active. - `TS-1061`: The “Allow POST requests” permission is off. - `TS-1063`: The “Check SMS status” permission is off. - `TS-1030`: The account is not active. - `TS-1020`: No message of yours was found with this ID. - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' examples: ts_1020_403: summary: '403' value: result: false result_code: TS-1020 result_message: The data sent is incorrect. '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/ResultError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ResultError' /reports/basic: post: tags: - Queries and reports operationId: reportsBasic summary: Summary report description: |- **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** This endpoint returns some failed results with HTTP 200. **Required permissions:** “Allow POST requests” and “Check SMS status” (API Center → My Keys → key → Scopes) Returns reports for group and scheduled sends. There are two endpoints: the **Summary report** gives the send's counters, and the **Detailed report** gives the delivery status per number. > **Note:** The `raporid` value is the `rapor_id` in the `/group/send` and `/group/sendMixed` response, or the `sms_id` in a scheduled `/sms/send` response. These endpoints use the `status` field instead of `result`; a successful response has no `result_message`. The counters change as the sending and delivery report processes progress. Full documentation: [Summary report](https://api.turkeysms.com.tr/documentation/english#ozet-rapor) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. raporid: type: integer description: Report ID. required: - api_key - raporid examples: example: summary: Example value: api_key: API_ANAHTARINIZ raporid: 482913377 responses: '200': description: |- OK: - `TS-1064`: The report was returned. - `TS-1029`: 400: `raporid` is missing or not a number. 200: the report was not found or does not belong to you. **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** Some failed results (`TS-1029`) are returned with HTTP 200. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ReportsBasicResponse' - $ref: '#/components/schemas/StatusError' examples: ts_1064_200_ok: summary: 200 OK value: status: success result_code: TS-1064 rapor_id: 482913377 total_numbers: 100 success_count: 90 failed_count: 5 pending_count: 5 details: sending_date: '2026-10-01' sending_time: '14:22:10' report_status: Currently in the process of being sent. sms_sender_id: BASLIGINIZ invalid_numbers: 2 blocked_numbers: 1 last_update: '2026-10-01 14:30:00' '400': description: |- Bad request: - `TS-1029`: 400: `raporid` is missing or not a number. 200: the report was not found or does not belong to you. - `TS-1033`: 400: the body is invalid. 404: wrong path. - `TS-1050`: `api_key` is missing. - `TS-1031`: The key is shorter than 30 characters, was not found or is not active. - `TS-1061`: The “Allow POST requests” permission is off. - `TS-1063`: The “Check SMS status” permission is off. - `TS-1030`: The account is not active. content: application/json: schema: $ref: '#/components/schemas/StatusError' '403': description: |- Forbidden: - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/StatusError' '404': description: |- Not found: - `TS-1033`: 400: the body is invalid. 404: wrong path. content: application/json: schema: $ref: '#/components/schemas/StatusError' '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/StatusError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/StatusError' /reports/detailed: post: tags: - Queries and reports operationId: reportsDetailed summary: Detailed report description: |- **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** This endpoint returns some failed results with HTTP 200. **Required permissions:** “Allow POST requests” and “Check SMS status” (API Center → My Keys → key → Scopes) Returns reports for group and scheduled sends. There are two endpoints: the **Summary report** gives the send's counters, and the **Detailed report** gives the delivery status per number. > **Note:** The `raporid` value is the `rapor_id` in the `/group/send` and `/group/sendMixed` response, or the `sms_id` in a scheduled `/sms/send` response. These endpoints use the `status` field instead of `result`; a successful response has no `result_message`. | details.status_code | sms_status | Meaning | |---|---|---| | `1` | `Number received the message` | Delivered. | | `2` | `Expiration time` | The validity period expired; not delivered. | | `0` | `Number didn't receive the message` | Not delivered, or the delivery report has not arrived yet. | `details.operator` values: `TURKCELL`, `VODAFONE`, `TURKTELEKOM`, `KKTCELL`, `TELSIM`, `UNKNOWN`. If there are no records yet (for example, if a scheduled send has not started), `data` is an empty array. An empty array is also returned for pages after the last page. Full documentation: [Detailed report](https://api.turkeysms.com.tr/documentation/english#detayli-rapor) requestBody: required: true content: application/json: schema: type: object properties: api_key: type: string description: Your API key. raporid: type: integer description: Report ID. page: type: integer description: 'Detailed report only: page number, `1` or greater. Default `1`. Each page returns at most 500 records.' required: - api_key - raporid examples: example: summary: Example value: api_key: API_ANAHTARINIZ raporid: 482913377 page: 1 responses: '200': description: |- OK: - `TS-1064`: The report was returned. - `TS-1029`: 400: `raporid` is missing or not a number. 200: the report was not found or does not belong to you. **Always check `result` (or `status`) and `result_code`, not only the HTTP status.** Some failed results (`TS-1029`) are returned with HTTP 200. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ReportsDetailedResponse' - $ref: '#/components/schemas/StatusError' examples: ts_1064_200_ok: summary: 200 OK value: status: success result_code: TS-1064 data: - phone_number: 905XXXXXXXXX sent_at: '2026-10-01 14:22:10' sms_status: Number received the message details: done_at: '2026-10-01 14:22:15' status_code: 1 operator: TURKCELL pagination: current_page: 1 total_pages: 3 total_records: 1203 records_per_page: 500 ts_1029_200_report_not_found: summary: 200 (report not found) value: status: error result_code: TS-1029 result_message: The Report ID is invalid or missing. '400': description: |- Bad request: - `TS-1029`: 400: `raporid` is missing or not a number. 200: the report was not found or does not belong to you. - `TS-1033`: 400: the body or `page` is invalid. 404: wrong path. - `TS-1050`: `api_key` is missing. - `TS-1031`: The key is shorter than 30 characters, was not found or is not active. - `TS-1061`: The “Allow POST requests” permission is off. - `TS-1063`: The “Check SMS status” permission is off. - `TS-1030`: The account is not active. content: application/json: schema: $ref: '#/components/schemas/StatusError' '403': description: |- Forbidden: - `TS-1035`: The key is paused, expired or revoked. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1066`: The request's IP address is not on the key's allowlist. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/StatusError' '404': description: |- Not found: - `TS-1033`: 400: the body or `page` is invalid. 404: wrong path. content: application/json: schema: $ref: '#/components/schemas/StatusError' '429': description: |- Too many requests: - `TS-1068`: The key's hourly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1069`: The key's daily request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). - `TS-1073`: The key's monthly request limit has been reached. See [Limits and IP allowlist](https://api.turkeysms.com.tr/documentation/english#limitler). content: application/json: schema: $ref: '#/components/schemas/StatusError' '500': description: |- Server error: - `SRV-ERR`: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/StatusError' components: schemas: ResultError: type: object description: Error envelope (`result` modules). properties: result: type: boolean const: false result_code: type: string result_message: type: string description: English text; may change. Use `result_code` in your program. required: - result - result_code StatusError: type: object description: Error envelope (Reports and Number blocking). properties: status: type: string const: error result_code: type: string result_message: type: string description: English text; may change. Use `result_code` in your program. required: - status - result_code AuthCheckResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string key_details: type: object properties: status: type: string description: The key's state. Because only active keys get a response, it is `Active` in a successful response. permissions: type: object properties: post_request: type: boolean send_single_sms: type: boolean send_otp: type: boolean check_balance: type: boolean check_senderid: type: boolean manage_groups: type: boolean send_group_sms: type: boolean send_otp_advanced: type: boolean create_group: type: boolean edit_group: type: boolean delete_group: type: boolean list_groups: type: boolean add_contact: type: boolean delete_contact: type: boolean block_number: type: boolean check_sms_status: type: boolean description: 16 permission fields (`true`/`false`). Their panel equivalents are in the operation description. account_summary: type: object properties: account_status: type: string description: The account's state. It is `Active` in a successful response. balance: type: object properties: main: type: integer description: The SMS credit in your account (integer). international: type: integer description: Additional fields. global_sending: type: boolean description: Additional fields. audit_info: type: object properties: request_ip: type: string description: The IP address the request came from. checked_at: type: string description: The date and time of the check. SmsSendResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string sms_id: type: integer description: The message ID of the last recipient. For single-recipient sends, use it with [SMS status query](https://api.turkeysms.com.tr/documentation/english#sms-durumu-sorgu). number_of_sms: type: integer description: The total SMS count for all recipients. total_recipients: type: integer description: The number of recipients after duplicates are removed. success_count: type: integer description: The number of recipients accepted for sending. It is not the number of delivered messages; for delivery status, use Webhook or SMS status query. sms_lang: type: string description: Labels for the values you sent. content_type: type: string description: Labels for the values you sent. country: type: string description: The country label of the first recipient (for example, `Turkey-TR`, or `GlobalSMS-GL` for international numbers). GroupSendResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string rapor_id: type: integer description: The send's report ID. Used as `raporid` in the [Reports](https://api.turkeysms.com.tr/documentation/english#raporlar) endpoints. total_numbers: type: integer description: The number of numbers queued after conversion and de-duplication. total_sms_cost: type: integer description: The total SMS count. scheduled: type: boolean description: '`true` if the send was scheduled.' GroupSendMixedResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string rapor_id: type: integer description: The send's report ID. Used as `raporid` in the [Reports](https://api.turkeysms.com.tr/documentation/english#raporlar) endpoints. total_numbers: type: integer description: The number of numbers queued after conversion and de-duplication. total_sms_cost: type: integer description: The total SMS count. scheduled: type: boolean description: '`true` if the send was scheduled.' OtpSendResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string sms_id: type: integer description: The message ID; can be used with [SMS status query](https://api.turkeysms.com.tr/documentation/english#sms-durumu-sorgu). otp_code: type: integer description: The code that was sent. It is returned as an integer and does not start with `0`. sandbox: type: boolean description: '`false` in live requests.' OtpDetailedResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string sms_id: type: integer description: The message ID. otp_code: type: integer description: The code that was sent. It is returned as an integer and does not start with `0`. number_of_sms: type: integer description: The SMS count of the message. sms_lang: type: string description: The label of the `lang` value. sandbox: type: boolean description: '`false` in live requests.' GroupsCreateResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string group: type: object properties: id: type: integer name: type: string created_at: type: string GroupsEditResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string new_name: type: string GroupsDeleteResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string GroupsListResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string groups_count: type: integer groups: type: array items: type: object properties: id: type: integer name: type: string date: type: string ContactsAddResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string group_id: type: integer total_sent: type: integer total_added: type: integer total_failed: type: integer mobile: type: string BlacklistAddResponse: type: object properties: status: type: string result_code: type: string result_message: type: string BlacklistStatusResponse: type: object properties: status: type: string result_code: type: string result_message: type: string is_blocked: type: boolean block_date: type: string block_time: type: string BalanceResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string balance_main: type: integer SenderidCheckResponse: type: object properties: result: type: boolean result_code: type: string result_message: type: string sender_ids_count: type: integer description: The number of Sender IDs in the list. sender_ids: type: array items: type: object properties: id: type: integer description: Sender ID record ID. title: type: string description: The Sender ID; used as `title` in sends. status: type: integer description: Always `1`, because only approved Sender IDs are listed. network_stat: type: integer description: Its values are not defined yet; do not use it in your integration. SmsStatusResponse: type: object properties: result: type: boolean result_code: type: string description: '`TS-1064`: the message was delivered. `TS-1022`: no delivery confirmation (the message could not be delivered or the delivery report has not arrived yet). Both are returned with `result: true` and HTTP 200.' result_message: type: string sender_id: type: string description: The Sender ID the message was sent with. date_of_sending: type: string description: The date and time the message was recorded. time_of_sending: type: string description: The date and time the message was recorded. sms_status: type: string description: '`Number received the message` or `The number did not receive the message`.' sms_balance: type: string description: The SMS count of this message (not the account balance). details: type: string description: The operation result; on a delivery error, the error description. operator: type: string description: The recipient's operator; may be empty if unknown. ReportsBasicResponse: type: object properties: status: type: string result_code: type: string rapor_id: type: integer total_numbers: type: integer description: The number of numbers in the send. success_count: type: integer description: The number of successful messages. failed_count: type: integer description: Failed messages, including invalid and blocked numbers. pending_count: type: integer description: Messages whose result is not known yet. details: type: object properties: sending_date: type: string description: The date and time the report was created (for a scheduled send, this is not the send time). sending_time: type: string description: The date and time the report was created (for a scheduled send, this is not the send time). report_status: type: string description: Text that describes the report's processing state. sms_sender_id: type: string description: The Sender ID used in the send. invalid_numbers: type: integer description: The number of invalid numbers and the number of blocked numbers. blocked_numbers: type: integer description: The number of invalid numbers and the number of blocked numbers. last_update: type: string description: The time the counters were last updated. ReportsDetailedResponse: type: object properties: status: type: string result_code: type: string data: type: array items: type: object properties: phone_number: type: string sent_at: type: string sms_status: type: string details: type: object properties: done_at: type: string status_code: type: integer operator: type: string pagination: type: object properties: current_page: type: integer total_pages: type: integer total_records: type: integer records_per_page: type: integer