Every business sending commercial SMS, email or voice messages in Turkiye has to log consent in the İleti Yönetim Sistemi (IYS), the national permission database set up under Law No. 6563. For a company with a few hundred contacts, the IYS web panel handles that fine.
When a CRM, online store, or marketing tool sends thousands of opt-ins and opt-outs, manual browser checks are no longer realistic. The sheer volume makes this approach unworkable. That gap is exactly what the IYS API exists to close.
This guide serves the person who builds the connection. That role is a developer, a technical lead, or an agency. They estimate an IYS integration's workload. The guide explains what the API does, how authentication works, and how the request cycle functions.
It also covers what registration involves and where integrations typically stumble. If you are looking for the compliance side instead, the deadlines, the fines, the registration paperwork, that ground is covered in our guide to IYS for small businesses.
Automating this connection does more than save time. It removes duplicate consent data that builds up across a CRM, an ERP and a marketing tool. Each system holds its own view of who said yes.
It cuts the human error that comes with manual entry. It keeps every system pointed at the one record that counts under Turkish law. That record lives inside IYS itself.
What Is the IYS API?
The İleti Yönetim Sistemi, IYS for short, is a central consent database run under Turkiye's Ministry of Trade. The IYS API is the RESTful interface that it exposes to outside systems. Through it, an application can add, check and remove permission records directly.
Every call runs over standard HTTP requests, with data sent and returned in JSON format. This matches the pattern a developer expects from any modern REST API.
IYS controls access with API credentials issued once your business is registered and approved. Those credentials identify your system to IYS on every call. They separate a legitimate integration from someone guessing at endpoints.
Authentication happens on every request, not once at login. A leaked key is a live problem the moment it leaks, not delayed. Treat credentials the way you would a database password, not a value that sits in a shared spreadsheet.
Core Operations: What the IYS API Actually Does
Underneath the marketing language, the IYS API supports three basic operations, and the whole system is organized by channel. Push a new approval in with a POST request. Check a contact's current status with GET.
Remove or update a permission with the equivalent of a DELETE call. IYS tracks three channels, SMS, email, and voice calls. It stores and queries each separately. A contact who approved email has not approved SMS automatically.
The part developers usually miss is that this is a two-way relationship, not a one-way push. Consent withdrawal can happen directly through e-Devlet or the IYS panel. Your system reports new approvals into IYS; IYS then reports those changes back to you.
To catch that, an integration needs a webhook that fires the moment a status changes. It can also use a polling job that checks for updates on a fixed schedule. A webhook gets you closer to real time and cuts the load on both sides. Polling is simpler to build, but a refusal can sit unprocessed for as long as the interval runs.
High-volume integrations also need to think about pace. IYS cannot absorb a multi-year contact list in one aggressive burst. Most integrators batch large migrations and rely on the webhook for the ongoing trickle of changes. They avoid hammering the query endpoint on a tight loop.
Getting API Access: Registration, Credentials, and Environments
API access is not something you can request on its own. Your business first registers as an IYS service provider through e-Devlet, the same process covered in our guide to IYS for e-commerce: confirming your MERSİS record, signing the usage agreement, and submitting your trademark documents through the official IYS platform. Your code calls with credentials that IYS issues after registration approval.
Most integrators, including Makdos, work through what IYS calls a Business Partner Code. A company registers you as its partner, and your systems handle the API traffic on its behalf. This is what lets an agency or hosting provider run the technical side. The client stays the registered legal entity.
Before any of this touches real customer data, build and test against a separate test environment. IYS, like most serious platforms, keeps sandbox data separate.
A wall separates it from the production environment that holds live consent records. Pointing a half-finished integration at production by mistake is the easiest way to corrupt real consent data. It is not always reversible.
A test environment and a production environment for IYS API access are not interchangeable, and pointing the wrong one at real customer data is the fastest way to break a consent record you cannot easily undo. Confirm which set of credentials your code is using before the first live run, not after.
Why Automate Instead of Running the Panel by Hand
The IYS web panel works fine at a small scale, but it does not scale with the business. A company adding a handful of contacts a week can type them in.
Someone spends real hours entering data for daily campaigns across a CRM, an ERP, and a marketing automation platform. A machine handles that entry more reliably than a person. The company cannot manage without it.
Automating this through the API does three things a manual panel workflow cannot. It automates the message-approval process itself. A new signup on your site reaches IYS the moment it happens, not whenever someone next logs into the panel.
It minimizes the human error that creeps into any process. That process depends on a person manually copying values from one screen to another. It keeps consent management consistent across every tool that touches customer data. Your CRM, your ERP and your IYS record do not quietly drift apart over time.
There is a compliance angle here too. KVKK, Turkiye's data protection law, and GDPR demand a business map where personal data lives. They also expect it to know who can touch it.
An API-driven flow logs everything and keeps a clear audit trail. It is easier to defend in that conversation than a spreadsheet someone updates when they remember to.
Choosing Your IYS Integration Method
| Method | Best suited to | Effort | Sync behavior |
|---|---|---|---|
| Web panel | A handful of contacts, occasional manual updates | Low setup, high ongoing effort | Checked and entered by hand |
| CSV bulk upload | Moving an existing list into IYS once | Medium setup, repeated per batch | Uploaded in batches, not continuous |
| IYS API | A CRM, storefront or marketing tool with daily signups and opt-outs | Higher setup, near-zero ongoing effort | Automatic, close to real time |
Most businesses start on the panel, then move to CSV for a one-time migration. Daily volume makes manual checking impractical, and teams reach for the IYS API at that point. Such a threshold arrives faster than expected.
Where IYS API Integrations Go Wrong
Most integration problems are not about the API itself failing. They are about a handful of predictable mistakes:
- Skipping the test environment. Teams build straight against production because the sandbox setup felt like an extra step. Then they find out the hard way that a bug touches real customer records.
- Treating webhook delivery as guaranteed. A webhook can fail to arrive, arrive twice, or arrive late. Without retry logic and state reconciliation, a missed delivery silently creates a gap in your consent record.
- No idempotency check. Retrying a failed request without checking whether the first attempt actually went through can double-log an approval. It can also send conflicting signals about a single contact's status.
- Ignoring the channel split. The system tracks SMS, email and voice consent separately. A query or update that does not specify the right channel can approve, or block, more than it should.
- Missing the reporting window. IYS expects you to report new approvals and opt-outs within three business days. An integration that batches updates slowly can quietly put approvals outside that window. No one notices until an audit asks for proof.
- Hardcoding credentials. API credentials committed into source control can turn a small mistake into a real security incident. Credentials left in a config file everyone can read do the same.
Verify the source of every webhook call rather than trusting the payload at face value. A webhook endpoint that accepts any POST without checking its origin is an easy target once its URL leaks.
None of these are exotic failures. They are the ordinary cost of treating an API integration as a one-time build. It is actually an ongoing piece of infrastructure that needs monitoring like anything else.
How Makdos Supports IYS API Integration
For most teams, the hard part of an IYS API integration is not the first working call. It is keeping that connection healthy for years while IYS updates its own rules and modules. Makdos is an IYS integrator authorized by the Ministry of Trade. That authorization lets us take on the technical side of this connection for another company.
Onboarding starts with the paperwork: guiding a client through the e-Devlet application and the business-partner step. Then we use the Business Partner Code IYS issues to link that account to ours. From there, a client's developers can work directly against the API with our documentation in hand, or lean on the Makdos IYS management panel if there is no in-house team ready to write the integration.
Either path gets the same webhook infrastructure underneath it. A signup on your website or a checkout confirmation reaches IYS on its own. A refusal filed anywhere, even directly through e-Devlet, flows back into your systems immediately.
This happens the moment it occurs rather than waiting for a scheduled sync. Consent records are personal data too, so the firewall and security services that protect the rest of your infrastructure cover this connection as well, keeping your KVKK obligations and your IYS integration moving together instead of running as two separate projects.
Support does not stop once the integration goes live. IYS occasionally changes its own API or adds a module. Makdos absorbs that change on our side instead of handing your team an urgent, unplanned rebuild. Our security team is available 24/7 for API errors, credential issues, or a webhook that stops firing mid-campaign.
Conclusion: Build the Connection Once, Let It Run
An IYS API integration is not a compliance checkbox you tick and forget. This is a live piece of infrastructure that must keep working every time a customer opts in or out. It has to run for as long as your business sends commercial messages in Turkiye.
Get the basics right, RESTful calls over JSON, and a real test environment separate from production. Add webhook handling that assumes messages can fail, and the rest holds up under real volume.
What should you do next? If you are still deciding between the panel, a CSV migration and a full API build, start by counting consent changes. Count how many your business handles in an average week; that number usually settles the question. If you already know you need the API and want the registration, credentials and ongoing support handled for you, review the Makdos IYS Integration Service and talk to our team about what your systems actually need to connect.
