Ana içeriğe geç

İ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.

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

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

Response

Success (200)

{
  "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.

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.

Code samples

cURL

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

Last updated: 2026-04-30 · Türkçe