Ana içeriğe geç

İYS Consent Register API (iys-register)

The iys-register endpoint creates İYS (İleti Yönetim Sistemi) consent records — the legally required Turkish national registry for commercial electronic messaging. Consents (or rejections) collected via web forms, signed contracts, call-center confirmations, etc. are submitted to iletiMerkezi through this endpoint and forwarded to the national İYS registry. Up to 5000 recipients per request.

İYS registration is mandatory for any commercial SMS sent in Turkey. Without a valid consent record, the corresponding send-sms call with iys: "1" is rejected with code 468 / 469 / 470.

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. Brand codes are issued after submitting a brand registration application from the panel. 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/create/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
   └─ list[] (array, required)        — 1-5000 consent records
      ├─ recipient (string, required)      — phone number or email
      ├─ recipientType (string, required)  — "BIREYSEL" (individual) or "TACIR" (business)
      ├─ type (string, required)           — "MESAJ", "EPOSTA", or "ARAMA"
      ├─ status (string, required)         — "ONAY" (consent) or "RET" (rejection)
      ├─ source (string, required)         — channel through which consent was obtained (see table)
      └─ consentDate (string, required)    — when consent was obtained, format "YYYY-MM-DD HH:MM:SS"

consentDate cannot be older than 3 days. Turkish İYS regulation requires consent records to be submitted within 3 days of actually being obtained; older timestamps are rejected with 422 — İstekte gönderilen bazı değerler doğrulanamadı ("Validation failure on request values").

source enum

The channel through which consent was originally obtained:

| Code | Meaning | |---|---| | HS_FIZIKSEL_ORTAM | Physical medium (printed form, brochure) | | HS_ISLAK_IMZA | Wet-ink signed contract | | HS_ETKINLIK | Event / fair / booth | | HS_EORTAM | Electronic medium (general) | | HS_WEB | Web form, website checkbox | | HS_MOBIL | Mobile app | | HS_MESAJ | Confirmed via SMS | | HS_EPOSTA | Confirmed via email | | HS_CAGRI_MERKEZI | Call-center voice confirmation | | HS_SOSYAL_MEDYA | Social media | | HS_ATM | ATM screen confirmation | | HS_KARAR | Administrative or judicial ruling |

Full example

A single recipient with ONAY (consent):

{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    },
    "consent": {
      "brandCode": 1234,
      "list": [
        {
          "recipient": "+905XXXXXXXXX",
          "recipientType": "BIREYSEL",
          "type": "MESAJ",
          "status": "ONAY",
          "source": "HS_WEB",
          "consentDate": "2026-04-30 09:15:42"
        }
      ]
    }
  }
}

Multiple recipients in one request:

"list": [
  { "recipient": "+905XXXXXXXX1", "recipientType": "BIREYSEL", "type": "MESAJ", "status": "ONAY", "source": "HS_WEB",  "consentDate": "2026-04-30 09:15:42" },
  { "recipient": "+905XXXXXXXX2", "recipientType": "BIREYSEL", "type": "MESAJ", "status": "ONAY", "source": "HS_WEB",  "consentDate": "2026-04-30 09:16:08" },
  { "recipient": "+905XXXXXXXX3", "recipientType": "BIREYSEL", "type": "MESAJ", "status": "RET",  "source": "HS_MESAJ","consentDate": "2026-04-30 09:18:27" }
]

Response

Success (200)

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

İşlem başarılı means "Request successful" in Turkish. All consent records in the request have been accepted by iletiMerkezi and queued for synchronization with the national İYS registry. The response is minimal — there is no per-record ID or partial-success breakdown; the batch is atomic — if any record fails validation the entire request fails with 422 and no records are persisted.

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. Resolution: start the İYS brand registration from your panel.

405 — Quota exceeded

Your subscription's monthly registration quota has been used up. Upgrade the plan from the panel or contact iletiMerkezi support.

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

Common causes:

  1. consentDate is more than 3 days old.
  2. recipient is not a valid phone number or email.
  3. recipientType, type, status, or source contains a value outside its allowed enum.
  4. brandCode does not belong to your account or is unprovisioned.

Validation is batch atomic — a single bad record fails the entire request.

475 — Alıcı sayısı 5000 kişiyi geçemez ("Recipient count exceeds 5000")

The consent.list array has more than 5000 entries. Split the list into 5000-record windows and call sequentially.

Other error codes

For 400, 404: see error-codes.md.

Code samples

cURL

curl -X POST 'https://api.iletimerkezi.com/v1/consent/create/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      },
      "consent": {
        "brandCode": 1234,
        "list": [
          {
            "recipient": "+905XXXXXXXXX",
            "recipientType": "BIREYSEL",
            "type": "MESAJ",
            "status": "ONAY",
            "source": "HS_WEB",
            "consentDate": "2026-04-30 09:15:42"
          }
        ]
      }
    }
  }'

Common pitfalls

  • Batch atomic — one bad record fails the whole batch. A single record in consent.list that fails validation drops the entire request with 422; the other records are not persisted. Test with a small slice (10-50 records) first, then run the full batch. Log who is in your batch on the client side so you can isolate the offending record.
  • consentDate is Turkey local time, not UTC. The format is YYYY-MM-DD HH:MM:SS in Turkey time (UTC+3). Sending UTC timestamps appears to work but skews real-world consent times by 3 hours, which becomes a problem at audit.
  • The 3-day rule starts when consent is obtained. Don't delay the API call after collecting consent. The consentDate is the moment your application got the user's signal; if you don't ship it within 3 days the request returns 422 and the record never reaches İYS.
  • source outside the enum = 422. Using web instead of HS_WEB, or inventing HS_FORM, fails validation. Stay within the table above.
  • RET is a positive action, not a delete. When a user opts out, you do not delete their consent record — you add a new record with status: "RET". At audit, the rejection is proven by this record.
  • type field vs. send-sms's iys field. iys-register adds a record to İYS; send-sms's iys: "1" + iysList triggers a registry check at send time (see send-sms). Two distinct operations; pre-loading via iys-register prevents send-sms from hitting 468 / 469 / 470 errors.
  • Panel and API are in sync. Consent records entered manually in the iletiMerkezi panel write to the same brandCode; to avoid duplicate records, decide upfront whether the panel or the API is the canonical writer.

Related

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