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

## 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):

```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.
- **`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)