---
title: "İYS Consent Query API (iys-check)"
description: "Look up the current İYS consent status for a single recipient: is consent on file, ONAY or RET, when and through which channel was it obtained."
slug: /en/docs/api/iys-check
locale: en
audience: developer
last_updated: 2026-04-30
endpoint:
  method: POST
  path: /v1/consent/show/json
  base_url: https://api.iletimerkezi.com
auth: api-key-and-hash
related: [iys-register, send-sms, authentication, error-codes]
alternates:
  tr: https://www.iletimerkezi.com/docs/api/iys-check
  en: https://www.iletimerkezi.com/en/docs/api/iys-check
  toplusmsapi: https://toplusmsapi.com/izin/sorgula/json
  a2psmsapi: https://a2psmsapi.com/en/izin/sorgula/json
---

# İYS Consent Query API (iys-check)

The `iys-check` endpoint returns the current İYS (İleti Yönetim Sistemi) consent status for a given recipient. Use it to verify a record submitted via `iys-register` has been processed, to check `ONAY` (consent) / `RET` (rejection) before a commercial send, or to produce audit reports. 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).

> **Brand code prerequisite.** Your account must have an active İYS brand code (`brandCode`) provisioned by iletiMerkezi. Without an active İYS subscription the request returns `403 — Aktif abonelik bulunamadı` ("No active subscription").

## Endpoint

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

## Request

### Schema

```
request
├─ authentication
│  ├─ key (string, required)
│  └─ hash (string, required)
└─ consent
   ├─ brandCode (string|integer, required) — your account's active İYS brand code
   ├─ recipient (string, required)         — phone number or email to look up
   ├─ recipientType (string, required)     — "BIREYSEL" (individual) or "TACIR" (business)
   └─ type (string, required)              — "MESAJ", "EPOSTA", or "ARAMA"
```

> The lookup is **single-recipient** — unlike `iys-register`, there is no list. For bulk audits, call once per recipient.

### Full example

```json
{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "consent": {
      "brandCode": 1234,
      "recipient": "+905XXXXXXXXX",
      "recipientType": "BIREYSEL",
      "type": "MESAJ"
    }
  }
}
```

## Response

### Success (200)

```json
{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "consent": {
      "brandCode": 1234,
      "recipient": "+905XXXXXXXXX",
      "recipientType": "BIREYSEL",
      "type": "MESAJ",
      "status": "ONAY",
      "source": "HS_WEB",
      "consentDate": "2026-04-30 09:15:42"
    }
  }
}
```

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

**Fields:**

- `response.consent.brandCode` (integer): the brand code used in the lookup.
- `response.consent.recipient` (string): the recipient (phone or email); phone numbers come back with the `+90` prefix.
- `response.consent.recipientType` (string): `BIREYSEL` or `TACIR`.
- `response.consent.type` (string): channel type — `MESAJ`, `EPOSTA`, or `ARAMA`.
- `response.consent.status` (string): current registry status — `ONAY` (consent on file) or `RET` (rejected / opted out).
- `response.consent.source` (string): the channel through which consent was obtained (e.g. `HS_WEB`); one of the `source` enum values from `iys-register`.
- `response.consent.consentDate` (string): when consent was obtained, format `YYYY-MM-DD HH:MM:SS`, Turkey local time.

> For the same `recipient + recipientType + type` combination, iletiMerkezi always returns the **most recent** record. If a customer first gave `ONAY` and later `RET`, the response is `status: "RET"`; that is binding and commercial messages are not allowed.

### Error responses

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

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

#### 403 — Aktif abonelik bulunamadı ("No active subscription")

Your account has no active İYS subscription. The brand code (`brandCode`) is missing or the İYS service is inactive.

#### 422 — İstekte gönderilen bazı değerler doğrulanamadı ("Validation failure on request values")

Common causes:
1. `recipient` is not a valid phone number or email.
2. `recipientType` or `type` is outside its allowed enum.
3. `brandCode` is empty or does not belong to your account.
4. No consent record exists for the recipient under this **brand + type** combination (recipient never registered).

> The "no record" case is also surfaced as 422 (not a separate 4XX). Check whether `consent.status` is present in the response rather than parsing the message string.

#### 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/consent/show/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      },
      "consent": {
        "brandCode": 1234,
        "recipient": "+905XXXXXXXXX",
        "recipientType": "BIREYSEL",
        "type": "MESAJ"
      }
    }
  }'
```


## Common pitfalls

- **`status: "ONAY"` means "legally allowed to send", not "always send".** `iys-check` only tells you the registry's current state. Your application's own opt-out list, blacklist, frequency caps, and KVKK disclosure flow must run independently.
- **`status: "RET"` is binding.** Sending a commercial message to a recipient with `RET` is rejected by `send-sms` (with codes 468 / 469 / 470) and exposes you to İYS complaints. Cache `RET` results client-side and add a blocking guard.
- **Single-recipient endpoint — beware of bulk lookups.** Calling once per record across a large customer list is slow and expensive. Practical pattern: keep the consent ledger on **your** side via `iys-register`, and use `iys-check` only for audits or single-user verification.
- **Be careful with caching.** A customer can issue `RET` from the panel or a different channel; long-TTL caches create legal risk. Cap caches at 1 hour, or invalidate on `RET` callbacks.
- **`recipient` format matters.** For phone numbers, `+905XXXXXXXXX`, `905XXXXXXXXX`, and `5XXXXXXXXX` are accepted; for email, the full address. Wrong formats return 422; on success the `+90` prefix is restored.
- **`type` overlaps with `send-sms`.** `send-sms` queries İYS automatically when called with `iys: "1"` + `iysList`; if you don't need an explicit pre-check, `iys-check` is optional. Use it only for audits, dashboards, or to verify state before failing.


## Related

- [İYS consent register (iys-register)](./iys-register.md) — create the record
- [Send SMS (send-sms)](./send-sms.md) — `iys` + `iysList` commercial-send fields
- [Authentication](./authentication.md)
- [Error code table](./error-codes.md)