---
title: "Get Blacklist API (get-blacklist)"
description: "Retrieve the list of blocked phone numbers on your account, with date filter and pagination."
slug: /en/docs/api/get-blacklist
locale: en
audience: developer
last_updated: 2026-04-29
endpoint:
  method: POST
  path: /v1/get-blacklist/json
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [add-blacklist, delete-blacklist, authentication, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/get-blacklist
  en: https://www.iletimerkezi.com/en/docs/api/get-blacklist
  toplusmsapi: https://toplusmsapi.com/numara-engelle/liste/json
  a2psmsapi: https://a2psmsapi.com/en/numara-engelle/liste/json
---

# Get Blacklist API (get-blacklist)

The `get-blacklist` endpoint returns the list of phone numbers that you have blocked on your account. Numbers on this list are skipped during `send-sms` delivery. 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-blacklist/json` |
| Content-Type | `application/json` |
| Auth | API Key + Hash (`request.authentication`) |

## Request

### Schema

```
request
├─ authentication
│  ├─ key (string, required)
│  └─ hash (string, required)
└─ blacklist (optional — pagination and filter)
   ├─ filter (optional)
   │  ├─ start (string)    — "YYYY-MM-DD HH:MM:SS"
   │  └─ end (string)      — "YYYY-MM-DD HH:MM:SS"
   ├─ page (string)        — default "1"
   └─ rowCount (string)    — default "1000", max "1000"
```

### Full example

Unfiltered, first page:

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

With a date filter:

```json
{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "blacklist": {
      "filter": {
        "start": "2026-04-01 00:00:00",
        "end": "2026-04-30 23:59:59"
      },
      "page": "1",
      "rowCount": "100"
    }
  }
}
```

## Response

### Success (200)

```json
{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "blacklist": {
      "count": 1,
      "number": [
        "+905330000099"
      ]
    }
  }
}
```

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

**Fields:**

- `response.blacklist.count` (integer): total count of blocked numbers on the account (independent of pagination).
- `response.blacklist.number` (string[]): blocked numbers on this page. Numbers come back with a `+90` prefix even if you submitted them as `905XXXXXXXXX`.

### Empty list (200)

```json
{
  "response": {
    "status": { "code": 200, "message": "İşlem başarılı" },
    "blacklist": { "count": 0, "number": [] }
  }
}
```

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


## Common pitfalls

- **Number format changes in the response.** You submit `905XXXXXXXXX`, the response returns `+905XXXXXXXXX`. Normalize both forms when comparing across systems.
- **Pagination capped at 1000.** `rowCount` max is 1000. Iterate `page` until you've seen `count` records.
- **`count` is global, not page-local.** It is the total number of blocked numbers on the account regardless of the current page; use it as the loop terminator.
- **`get-blacklist` consumes no credits.** Caching is the practical pattern; you don't need to call it before every `send-sms`.


## Related

- [Add to blacklist (add-blacklist)](./add-blacklist.md)
- [Remove from blacklist (delete-blacklist)](./delete-blacklist.md)
- [Authentication](./authentication.md)
- [Error code table](./error-codes.md)