iletiMerkezi API Authentication

The iletiMerkezi REST API authenticates requests with an API Key + Hash pair. Both values are issued by the panel; you do not compute them at runtime. They travel inside the JSON body under request.authentication, not as a separate HTTP header.

Prerequisite: enable API access in the panel

Before your first request, 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 — Authentication failed. This does not mean your key is wrong; it means the toggle is closed. More than 90% of developers hit this on their first attempt.

Where to find your credentials

Open panel.iletimerkezi.com → Settings → Security → API Access.
Copy the API Key and API Hash from the panel. Both are hex strings.
Store them as environment variables in your application:

ILETIMERKEZI_API_KEY=...
ILETIMERKEZI_API_HASH=...

Do not generate the hash yourself. The iletiMerkezi panel issues a precomputed hash; SDKs and direct HTTP clients pass it through unchanged. There is no MD5 / SHA / HMAC step in your code.

Request format

Every endpoint is called with POST and shares the same body envelope:

| Field | Value | |---|---| | Method | POST | | URL | https://api.iletimerkezi.com/v1/{endpoint}/json | | Content-Type | application/json | | Auth field | request.authentication.{key, hash} |

Auth block

{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    }
  }
}

Each endpoint adds its own fields next to this block. For get-balance no extra fields are needed:

{
  "request": {
    "authentication": {
      "key": "API_KEY",
      "hash": "API_HASH"
    }
  }
}

For send-sms you add a message field; see send-sms.md for details.

Verifying your credentials

The fastest way to confirm your keys work is to call get-balance. It has no side effects, does not consume credits, and can be retried safely.

curl -X POST 'https://api.iletimerkezi.com/v1/get-balance/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "API_KEY",
        "hash": "API_HASH"
      }
    }
  }'

Successful response (HTTP 200):

{
  "response": {
    "status": {
      "code": 200,
      "message": "İşlem başarılı"
    },
    "balance": {
      "amount": 10.584,
      "sms": 69
    }
  }
}

Note: status messages are returned in Turkish. İşlem başarılı means "Request successful". If you receive this body, authentication is working and you can call other endpoints.

Error responses

401 — Authentication failed

{
  "response": {
    "status": {
      "code": 401,
      "message": "Üyelik bilgileri hatalı"
    }
  }
}

The Turkish message reads "Membership information is invalid".

Most common causes (in order):

The "Allow API access" toggle is off in the panel. This is the leading cause of first-attempt 401 errors. The message is generic, so it is easy to misread as a credential problem.
API Key or Hash copied incorrectly. Re-check the values in your environment variables against the panel; pay attention to leading and trailing whitespace.
IP restriction is enabled but the request's source IP is not whitelisted. If you have configured an API IP whitelist under Settings → Security → Static IP, requests from any other IP return 401. Add your server's outbound IP to the list, or disable the restriction.
Key has been rotated or disabled. Generate a new key in the panel and update your application.

Full error code table: error-codes.md

Code samples

cURL

curl -X POST 'https://api.iletimerkezi.com/v1/get-balance/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "request": {
      "authentication": {
        "key": "'"$ILETIMERKEZI_API_KEY"'",
        "hash": "'"$ILETIMERKEZI_API_HASH"'"
      }
    }
  }'

Common pitfalls

Panel toggle 401. The number-one first-time failure. The message says "Authentication failed" but the real cause is that API access is disabled. Check the panel before rotating keys for hours.
Do not compute the hash yourself. Older guides on the internet may show MD5 or SHA pipelines. iletiMerkezi issues the hash from the panel; computing it client-side will produce a wrong value and a 401.
Never commit credentials. API Key and Hash carry full account permissions. Store them in .env, Vault, AWS Secrets Manager, or your CI's secret store, never in source control.
Do not test by sending SMS. Use get-balance to verify auth. send-sms consumes credits on every successful call and delivers a real message to the destination number.
There is no separate sandbox key. The same key works for both development and production. New accounts receive 100 free SMS credits for testing and evaluation, which covers the first integration without extra cost. Standard pattern: a "TEST" prefix in the message body and your own verified test number as the recipient.

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