--- title: "İYS Consent Register API (iys-register)" description: "Register İYS (Turkish messaging consent registry) records for the recipients you intend to send commercial messages to. Up to 5000 recipients per request." slug: /en/docs/api/iys-register locale: en audience: developer last_updated: 2026-04-30 endpoint: method: POST path: /v1/consent/create/json base_url: https://api.iletimerkezi.com auth: api-key-and-hash related: [iys-check, send-sms, authentication, error-codes] alternates: tr: https://www.iletimerkezi.com/docs/api/iys-register en: https://www.iletimerkezi.com/en/docs/api/iys-register toplusmsapi: https://toplusmsapi.com/izin/ekle/json a2psmsapi: https://a2psmsapi.com/en/izin/ekle/json --- # İ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](./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"). > **Important, a `200` response is not a confirmation.** A `200 İşlem başarılı` response means the request was accepted; it is not a confirmation that the record landed in the national İYS registry. Invalid `brandCode` values or `source` values that aren't accepted in this context (e.g. `HS_KARAR` for an initial consent) can in some cases return a silent `200` instead of an error. For critical flows (compliance audit, customer dispute), verify the record afterwards with [`iys-check`](./iys-check.md) using the same `recipient + recipientType + type` triple; an empty `consent: []` means the record never reached the registry. ## 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 (cannot be used for the first registration) | ### Full example A single recipient with `ONAY` (consent): ```json { "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: ```json "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) ```json { "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](./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](./error-codes.md). ## Code samples ### cURL ```bash 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. - **`HS_KARAR` cannot be used for the first registration.** A service provider cannot create a recipient's first consent record with `source: "HS_KARAR"`; this code is reserved for **subsequent** status updates that follow an administrative or judicial ruling. Sending it on the first record returns 422. - **`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](./send-sms.md)). 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 - [İYS consent query (iys-check)](./iys-check.md), verify state after registering - [Send SMS (send-sms)](./send-sms.md), `iys` + `iysList` commercial-send fields - [Authentication](./authentication.md) - [Error code table](./error-codes.md)