API Documentation

Every request sends key and action. In a successful response status is success, in a failed one it is error; on error, code and message are returned.

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=balance"

Example error response

{
    "status": "error",
    "message": "API Key could not be validated",
    "code": 102
}

Errors any action can return

Order statuses

Returns your account's current balance.

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=balance"

Example response

{
    "status": "success",
    "balance": 250.75,
    "currency": "TRY"
}

Lists your orders from newest to oldest (My Orders and Rented Numbers).

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=orders" \
  -d "limit=20"

Example response

{
    "status": "success",
    "currency": "TRY",
    "data": [
        {
            "id": 73,
            "type": "ACTIVATION",
            "service": 29,
            "service_name": "Tinder",
            "country": "US",
            "number": "12034653202",
            "status": "RECEIVED",
            "code": "609648",
            "charge": 19.07,
            "created_at": "2026-11-02 06:15:14",
            "end_date": null
        }
    ]
}

Error codes

Active countries. In other actions, the country is sent as its cca2 code.

Active countries and CCA2 codes (0)

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=countries"

Example response

{
    "status": "success",
    "countries": [
        {
            "name": "Türkiye",
            "common_name": "Turkey",
            "key": "turkey",
            "cca2": "TR"
        }
    ]
}

Operators accepting orders. When getting a number, set operator to the operator's id value; price and stock vary by operator.

Active operators

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=operators"

Example response

{
    "status": "success",
    "operators": [
        {
            "id": 8,
            "name": "Operator - 1",
            "minutes": 20,
            "cancel_after": 2,
            "rebuy": true
        }
    ]
}

minutes: how long the number can be used (minutes). cancel_after: how many minutes after ordering it can be cancelled. rebuy: whether the number can be bought again after it expires.

Services in stock, with price (TRY) and stock by country and operator. The full list is large, so filtering by country is recommended.

Active services and service IDs (0)

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=services" \
  -d "country=TR"

Example response

{
    "status": "success",
    "currency": "TRY",
    "data": {
        "TR": {
            "name": "Türkiye",
            "common_name": "Turkey",
            "key": "turkey",
            "operators": {
                "8": {
                    "name": "Operator - 1",
                    "services": {
                        "29": {
                            "name": "Tinder",
                            "charge": 22.44,
                            "quantity": 3697
                        }
                    }
                }
            }
        }
    }
}

Error codes

Price and stock of a service in the selected country. If no operator is sent, all active operators are returned.

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=get_service" \
  -d "service=29" \
  -d "country=TR"

Example response

{
    "status": "success",
    "service": {
        "id": 29,
        "name": "Tinder",
        "country": "TR",
        "operator": 8,
        "charge": 22.44,
        "quantity": 3697,
        "currency": "TRY"
    }
}

If no operator is sent, charge ve quantity yerine data , where per operator ID name, charge, quantity are returned.

Error codes

Buys a single-use number; the cost is deducted from your balance. Use status or messages to check the incoming code.

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=get_number" \
  -d "service=29" \
  -d "country=TR" \
  -d "operator=8"

Example response

{
    "status": "success",
    "data": {
        "id": 73,
        "service": 29,
        "country": "TR",
        "provider": 8,
        "number": "905321234567",
        "charge": 22.44,
        "currency": "TRY",
        "status": "PENDING"
    }
}

Error codes

Order status, received codes and end time. Single-use orders are updated on the server once a minute.

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=status" \
  -d "order=73"

Example response

{
    "status": "success",
    "data": {
        "id": 73,
        "number": "905321234567",
        "type": "ACTIVATION",
        "status": "RECEIVED",
        "code": "609648",
        "codes": [
            "609648"
        ],
        "charge": 22.44,
        "currency": "TRY",
        "created_at": "2026-11-02 06:15:14",
        "end_date": "2026-11-02 06:35:14"
    }
}

Error codes

SMS received for the order (oldest to newest). Query by order ID or number; if the same number is on several orders, the newest one is used.

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=messages" \
  -d "order=73"

Example response

{
    "status": "success",
    "order": 73,
    "data": [
        "Tinder kodun: 609648"
    ],
    "messages": [
        {
            "text": "Tinder kodun: 609648",
            "code": "609648",
            "date": "2026-11-02 06:24:51"
        }
    ]
}

Error codes

Cancels a single-use order that has not received an SMS; the cost is refunded to your balance. It cannot be cancelled before the operator's cancel wait time has passed.

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=cancel" \
  -d "order=73"

Example response

{
    "status": "success",
    "data": {
        "id": 73,
        "status": "CANCELED",
        "refund": 22.44,
        "currency": "TRY"
    }
}

Error codes

Returns the price of buying the number from an expired, completed (FINISHED) order again. You are not charged.

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=rebuy_price" \
  -d "order=73"

Example response

{
    "status": "success",
    "data": {
        "order": 73,
        "number": "905321234567",
        "charge": 22.44,
        "currency": "TRY",
        "minutes": 20
    }
}

minutes: how long the rebought number can be used (minutes).

Error codes

Buys the number from an expired, completed order again; a new order is created and the cost is deducted from your balance.

Parameters

Example request

curl -X POST https://mail.premiumsms.net/api/v1 \
  -d "key=API_ANAHTARINIZ" \
  -d "action=rebuy" \
  -d "order=73"

Example response

{
    "status": "success",
    "data": {
        "id": 74,
        "number": "905321234567",
        "charge": 22.44,
        "currency": "TRY",
        "status": "PENDING"
    }
}

Error codes