---
title: "Add Blacklist API (add-blacklist)"
description: "Add a phone number to your blacklist so send-sms skips delivery to it. Idempotent: re-adding returns 200, not an error."
slug: /en/docs/api/add-blacklist
locale: en
audience: developer
last_updated: 2026-04-29
endpoint:
  method: POST
  path: /v1/add-blacklist/json
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [get-blacklist, delete-blacklist, authentication, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/add-blacklist
  en: https://www.iletimerkezi.com/en/docs/api/add-blacklist
  toplusmsapi: https://toplusmsapi.com/numara-engelle/ekle/json
  a2psmsapi: https://a2psmsapi.com/en/numara-engelle/ekle/json
---

# Add Blacklist API (add-blacklist)

The `add-blacklist` endpoint adds one phone number to your account's blacklist so it is skipped by `send-sms`. **Idempotent**: re-adding the same number returns 200 instead of an error. One number per request.

## 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/add-blacklist/json` |
| Content-Type | `application/json` |
| Auth | API Key + Hash (`request.authentication`) |

## Request

### Schema

```
request
├─ authentication
│  ├─ key (string, required)
│  └─ hash (string, required)
└─ blacklist
   └─ number (string, required) — one number, 905XXXXXXXXX / +905XXXXXXXXX / 5XXXXXXXXX
```

### Full example

```json
{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "blacklist": {
      "number": "905XXXXXXXXX"
    }
  }
}
```

## Response

### Success (200)

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

`İşlem başarılı` means "Request successful" in Turkish. The number is now blocked. Re-adding the same number returns the same 200.

### Error responses

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

See [authentication.md](./authentication.md).

#### 466 — Hatalı numara ("Invalid number")

The number does not match a Turkish carrier prefix (50 / 53 / 54 / 55, etc.). Use a valid Turkish mobile number such as `+905330000099`. Made-up prefixes like `905999XXXXXXX` are rejected.

#### 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/add-blacklist/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      },
      "blacklist": { "number": "905XXXXXXXXX" }
    }
  }'
```


## Common pitfalls

- **Idempotent.** Re-adding the same number is a no-op that returns 200. No need for a `try/except 466`-style guard or a pre-check via `get-blacklist`.
- **One number per request.** `blacklist.number` is a string, not an array. For bulk adds, loop through and call once per number (mind your rate limits).
- **466 = invalid Turkish carrier prefix.** `+905330000099` works; `+905999000000` is rejected. International numbers (e.g. `+49...`) appear in the legacy spec example, but live carrier acceptance varies; test from your own account before production use.
- **Number format flexible, response uses `+90` prefix.** `905...`, `+905...`, and `5...` are all accepted on input; `get-blacklist` returns them as `+905XXXXXXXXX`.


## Related

- [Get blacklist](./get-blacklist.md)
- [Remove from blacklist (delete-blacklist)](./delete-blacklist.md)
- [Authentication](./authentication.md)
- [Error code table](./error-codes.md)