---
title: "Approved Sender IDs API (get-sender)"
description: "Retrieve the list of sender IDs (headers) approved on your account. Use it to validate the sender before send-sms calls."
slug: /en/docs/api/get-sender
locale: en
audience: developer
last_updated: 2026-04-29
endpoint:
  method: POST
  path: /v1/get-sender/json
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [authentication, send-sms, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/get-sender
  en: https://www.iletimerkezi.com/en/docs/api/get-sender
  toplusmsapi: https://toplusmsapi.com/sms/baslik/liste/json
  a2psmsapi: https://a2psmsapi.com/en/sms/baslik/liste/json
---

# Approved Sender IDs API (get-sender)

The `get-sender` endpoint returns the list of **sender IDs (headers)** registered and approved on your account. The `order.sender` field of [`send-sms`](./send-sms.md) only accepts values from this list; using anything else is rejected. The call has no side effects and consumes no credits.

## Prerequisite: enable API access in the panel

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

## Endpoint

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

## Request

### Schema

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

`get-sender` takes no extra fields beyond the auth block.

### Full example

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

## Response

### Success (200)

```json
{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "senders": {
      "sender": [
        "eMarka Test"
      ]
    }
  }
}
```

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

**Fields:**

- `response.senders.sender` (string[]): Array of approved sender IDs. Single-sender accounts return a one-element array; multi-sender accounts return more. Each ID is at most 11 characters, alphanumeric (spaces count).

> New accounts may receive an empty array. Sender ID applications are submitted from the panel and reviewed by iletiMerkezi within 1-2 business days; once approved, the ID appears here automatically.

### Error responses

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

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

#### Other error codes

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

## Code samples

### cURL

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


## Common pitfalls

- **Empty list means approval is pending.** New accounts get an empty array (`[]`). Submit your sender ID application from the panel; iletiMerkezi reviews it within 1-2 business days. While approval is pending, you can pass `"APITEST"` as the sender in `send-sms` to test the HTTP flow end-to-end. See [test-mode](./test-mode.md).
- **Validate the sender at runtime.** In production, check that `order.sender` is in this list before calling `send-sms`. A bad sender ID floods your error logs in production.
- **11-character cap.** Maximum 11 alphanumeric characters; spaces count (`eMarka Test` = 11 chars).
- **The list rarely changes.** Approvals are infrequent. You don't need to call `get-sender` before every `send-sms`. Cache the list at application start or refresh on a panel-driven event.
- **Sender ID is case-sensitive.** If the panel approved `eMarka Test`, send `eMarka Test` exactly; `emarka test` or `EMARKA TEST` may be rejected.


## Related

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