Developer API · v1.0

API reference

Virtual number activations and rent: prices, purchase, SMS codes, balance and an incoming-SMS webhook.

vpn_keyKeys & webhooks
Serverhttps://simdrop.io/api/v1
AuthenticationX-Api-Key: sdk_YOUR_API_KEY
Currencies?currency=RUB|USD

#Introduction

The Developer API gives programmatic access to Simdrop activations and rent: prices, purchase, receiving SMS codes, history, balance and a webhook for incoming SMS. It is a JSON REST API over HTTPS: readable string statuses, prices in your currency and per-activation action flags.

Base URL

text
https://simdrop.io/api/v1

Quick start

  • Create an API key in the dashboard (“API” page). The key is shown once — store it safely.
  • Fetch prices: GET /prices?service=tg — each price tier has a priceId.
  • Buy a number: POST /activations with service, country and priceId (or maxPrice).
  • Wait for the code: set a webhook in the dashboard (you get a POST with the code) or poll GET /activations/{id} every 3–5 seconds.
  • Finish with POST /activations/{id}/finish (or cancel with DELETE if no code arrived — you get refunded).
Minimal example
# 1. цены
curl 'https://simdrop.io/api/v1/prices?service=tg&country=0' -H 'X-Api-Key: sdk_...'

# 2. покупка
curl -X POST 'https://simdrop.io/api/v1/activations' \
  -H 'X-Api-Key: sdk_...' -H 'Content-Type: application/json' \
  -d '{"service":"tg","country":0,"maxPrice":30}'

# 3. код
curl 'https://simdrop.io/api/v1/activations/3051287731' -H 'X-Api-Key: sdk_...'

#Authentication

Every request carries your API key in the X-Api-Key header (alternatively Authorization: Bearer <key>). Passing the key in the query string is not supported: it would leak into proxy logs and browser history.

http
GET /api/v1/account/balance HTTP/1.1
Host: simdrop.io
X-Api-Key: sdk_2f9c1e...
Accept-Language: ru

Multiple keys and scopes

You can create up to 5 keys in the dashboard — e.g. one per server or bot. Each key has its own scopes, IP allowlist, default currency and expiry. A key can be rotated (the old one stops working immediately) or revoked.

ScopeGrants access to
readcatalog, prices, balance, history, reading activations and SMS
activationspurchase, cancel, finish, retry SMS, replace, reactivate
rentrenting numbers and extending rent

Security recommendations

  • Restrict the key to your servers’ IPs (allowlist) — requests from other IPs get 403 IP_NOT_ALLOWED.
  • Grant the minimum scopes: balance monitoring only needs read.
  • Set an expiry on temporary keys and rotate on any suspicion of a leak.
  • The dashboard shows the last 50 requests per key (method, path, status, IP) — useful for debugging and monitoring.

#Currencies & prices

Your balance is kept in RUB. All amounts in API responses (prices, balance, transactions) can be returned in RUB or USD: add ?currency=USD to any request or set the key’s default currency in the dashboard. Every object with an amount carries a currency field.

  • USD is converted at the USDT/RUB rate (CoinGecko, cached for 5 minutes). The current rate is exposed in GET /account/balance?currency=USD (usdRubRate).
  • Rounding: RUB — 2 decimals, USD — 4 decimals.
  • maxPrice on purchase is interpreted in the request currency.
  • If the rate is temporarily unavailable and USD was requested, you get 503 EXCHANGE_RATE_UNAVAILABLE — retry or use RUB.
  • Top-ups are done in the dashboard, always in RUB.
bash
curl 'https://simdrop.io/api/v1/prices?service=tg&country=0&currency=USD' -H 'X-Api-Key: sdk_...'

#Responses & errors

A successful response is always wrapped in an object with a data field. Lists also carry meta with pagination (page starts at 1, size ≤ 100).

json
{
  "data": [
    {
      "id": 3051287731,
      "status": "WAITING"
    }
  ],
  "meta": {
    "page": 1,
    "size": 25,
    "total": 1,
    "hasMore": false
  }
}

An error is an object with a machine-readable error code (stable contract), a human-readable message (language follows Accept-Language: ru or en) and optional details.

json
{
  "error": "NO_NUMBERS",
  "message": "No numbers available right now. Try another price tier, operator or country",
  "details": {
    "service": "tg",
    "country": 0
  }
}
HTTPCodeWhen
400BAD_REQUEST, INVALID_CURRENCY, INVALID_PRICEMalformed parameters
401UNAUTHORIZED, KEY_EXPIREDNo key, key revoked or expired
402INSUFFICIENT_FUNDSNot enough balance
403IP_NOT_ALLOWED, INSUFFICIENT_SCOPE, API_ACCESS_DISABLED, PURCHASE_BLOCKEDAccess denied
404ACTIVATION_NOT_FOUND, OFFER_NOT_FOUND, WEBHOOK_NOT_FOUND, NOT_FOUNDObject not found
409NO_NUMBERS, NO_OFFER_UNDER_MAX_PRICE, ACTIVE_LIMIT_REACHED, PURCHASE_IN_PROGRESS, COUNTRY_BLOCKED, SERVICE_UNAVAILABLE, CANCEL_TOO_EARLY, CANCEL_NOT_ALLOWED, FINISH_NOT_ALLOWED, RETRY_NOT_AVAILABLE, REPLACE_NOT_AVAILABLE, REACTIVATION_UNAVAILABLE, PROLONG_UNAVAILABLE, NOT_A_RENTState conflict — the action is not possible right now
422VALIDATION_ERRORField validation failed (details.fields)
429RATE_LIMITEDRate limit, see Retry-After
502 / 503PROVIDER_ERROR, EXCHANGE_RATE_UNAVAILABLETemporary issues — retry later
infoDates are ISO 8601 in UTC (2026-09-13T20:41:12Z). Activation ids are 64-bit integers: in JavaScript handle them carefully or use BigInt.

#Rate limits

Limits protect both you and us from runaway loops and abuse. They are tracked in Redis and apply across all API replicas.

LevelLimitApplies to
Per key120 requests / minuteall requests with the key
Purchases20 / minute and 1500 / hourPOST /activations, /rent, replace, reactivate, prolong
Heavy catalog40 / minuteGET /prices, /rent/prices, /services, /rent/services, /operators
Per IP600 / minuteall requests from the address regardless of the key
Key brute force20 failed authentications / 10 minutesinvalid keys from one IP

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining (the key’s general limit). On 429 you get Retry-After in seconds — wait and retry. Additionally, an account may have between 10 and 100 simultaneously active activations depending on your rank (ACTIVE_LIMIT_REACHED) and one purchase at a time (PURCHASE_IN_PROGRESS).

warning_amberDo not poll an activation more often than every 3 seconds. Webhooks are the best option: the code is pushed to you the moment it arrives, without a single extra request.
infoCatalog and price endpoints (/countries, /services, /operators, /prices, /rent/*) are cached on our side for 45–300 seconds, so available counts may update with a slight delay — that is expected; at purchase time price and availability are always checked live.

#Statuses & lifecycle

StatusMeaning
WAITINGNumber issued, waiting for SMS
WAITING_RETRYAnother SMS requested
RECEIVEDCode received, the activation can be finished
FINISHEDFinished (confirmed by you or expired with a received code)
CANCELLEDCancelled, refunded (incl. expired without SMS)
REPLACEDNumber replaced — use the new activation

Rules

  • A one-time activation lives for 20 minutes. If no SMS arrives it is cancelled automatically with a refund.
  • Cancellation (DELETE) is possible 2 minutes after purchase and only until a code is received.
  • Number replacement (replace) is free, available in WAITING 2 minutes after purchase, at most 3 times. The old activation becomes REPLACED; the response contains the new one.
  • Rent can be cancelled within 2–20 minutes after purchase if no SMS arrived. It can be finished early (finish) at any time without a refund.
  • The actions field of each activation tells which actions are available right now — same rules as the dashboard buttons.

#Webhooks

A webhook is an HTTPS POST to your URL the moment an SMS (or a call with a code) arrives on your number. An account has a single webhook URL, configured in the dashboard on the “API” page; a test-delivery button and the delivery log are there too.

EventWhen it is sent
sms.receivedAn SMS or a call with a code arrived for an active activation or rent
webhook.testTest delivery from the dashboard

Request format

http
POST /your/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Simdrop-Webhooks/1.0
X-Simdrop-Event: sms.received
X-Simdrop-Delivery-Id: 6f2b0c1e-9a3d-4c7e-8f01-2d5e6a7b8c9d
json
{
  "id": "6f2b0c1e-9a3d-4c7e-8f01-2d5e6a7b8c9d",
  "event": "sms.received",
  "createdAt": "2026-09-13T20:41:12Z",
  "data": {
    "activation": {
      "id": 3051287731,
      "type": "activation",
      "status": "RECEIVED",
      "phone": "79991234567",
      "countryPhoneCode": "7",
      "service": "tg",
      "country": 0,
      "operator": "mts",
      "verificationType": "sms",
      "price": 25.5,
      "currency": "RUB",
      "code": "482913",
      "sms": [
        {
          "type": "sms",
          "code": "482913",
          "text": "Your Telegram code is 482913",
          "receivedAt": "2026-09-13T20:41:12Z"
        }
      ],
      "canGetAnotherSms": true,
      "replaceCount": 0,
      "createdAt": "2026-09-13T20:38:02Z",
      "activatedAt": "2026-09-13T20:38:02Z",
      "expiresAt": "2026-09-13T20:58:02Z",
      "updatedAt": "2026-09-13T20:41:12Z",
      "actions": {
        "cancel": false,
        "finish": true,
        "retry": true,
        "replace": false,
        "reactivate": false,
        "prolong": false
      }
    },
    "sms": {
      "type": "sms",
      "code": "482913",
      "text": "Your Telegram code is 482913",
      "receivedAt": "2026-09-13T20:41:12Z"
    }
  }
}

Amounts in the payload are always in RUB. Respond with any 2xx status within 10 seconds — the response body is ignored. Anything else or a timeout counts as a failure: retries after 30 s, 2 min, 10 min, 30 min, 2 h (6 attempts total). After 100 consecutive failures the endpoint is disabled automatically — re-enable it in the dashboard once fixed.

Verifying the sender by IP

Webhooks always come from one of two IP addresses. If you want to be sure a request really comes from Simdrop, allow only these on your server (e.g. in nginx or in the handler code). Process deliveries idempotently by the id field: on network hiccups the same event may arrive twice.

Sender IP addresses
93.127.155.137
45.80.7.136
Node.js (Express)
import express from "express";

const ALLOWED_IPS = new Set(["93.127.155.137","45.80.7.136"]);
const app = express();
app.set("trust proxy", true); // если перед приложением стоит nginx/балансировщик

app.post("/simdrop/webhook", express.json(), (req, res) => {
  if (!ALLOWED_IPS.has(req.ip)) {
    return res.status(403).end();
  }
  const event = req.body;
  if (event.event === "sms.received") {
    console.log("code for activation", event.data.activation.id, "=", event.data.sms.code);
  }
  res.status(200).end();
});
Python (Flask)
from flask import Flask, request, abort

ALLOWED_IPS = {"93.127.155.137", "45.80.7.136"}
app = Flask(__name__)

@app.post("/simdrop/webhook")
def webhook():
    ip = request.headers.get("X-Forwarded-For", request.remote_addr).split(",")[0].strip()
    if ip not in ALLOWED_IPS:
        abort(403)
    event = request.get_json()
    if event["event"] == "sms.received":
        print("code:", event["data"]["sms"]["code"])
    return "", 200
PHP
<?php
$allowedIps = ['93.127.155.137', '45.80.7.136'];
$ip = $_SERVER['HTTP_X_FORWARDED_FOR'] ?? $_SERVER['REMOTE_ADDR'];
$ip = trim(explode(',', $ip)[0]);
if (!in_array($ip, $allowedIps, true)) {
    http_response_code(403);
    exit;
}
$event = json_decode(file_get_contents('php://input'), true);
if ($event['event'] === 'sms.received') {
    error_log('code: ' . $event['data']['sms']['code']);
}
http_response_code(200);
warning_amberEndpoint requirements: https:// only, a public host (localhost and private networks are rejected), no credentials in the URL, redirects are not followed.

#Account

Account balance in the request currency.

GET/account/balance

Balance

Current balance — purchases are charged from it, there are no holds on it. With currency=USD the conversion rate is returned too.

keyscope: read

Query parameters

currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

GET/account/balance
curl -X GET 'https://simdrop.io/api/v1/account/balance?currency=USD' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": {
    "balance": 13.4521,
    "currency": "USD",
    "usdRubRate": 92.95
  }
}
OK

#Catalog & prices

Countries, services, operators and current purchase / rent prices.

GET/countries

Countries

All available countries. The country id is used in other methods.

keyscope: read

Responses

GET/countries
curl -X GET 'https://simdrop.io/api/v1/countries' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": [
    {
      "id": 0,
      "name": "Russia",
      "nameRu": "Россия",
      "phoneCode": "+7",
      "rent": true,
      "retry": true
    },
    {
      "id": 6,
      "name": "Indonesia",
      "nameRu": "Индонезия",
      "phoneCode": "+62",
      "rent": true,
      "retry": true
    }
  ],
  "meta": {
    "page": 1,
    "size": 2,
    "total": 2,
    "hasMore": false
  }
}
OK
GET/services

Services

Service catalog (Telegram, WhatsApp, …) with minimum price and available count. Supports search and pagination.

keyscope: read

Query parameters

searchstring
Search by name/code Example: tele
pageinteger
Page number, starting at 1 Example: 1
sizeinteger
Page size (default 50, max 100) Example: 50
currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

GET/services
curl -X GET 'https://simdrop.io/api/v1/services' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": [
    {
      "code": "tg",
      "name": "Telegram",
      "minPrice": 18.5,
      "currency": "RUB",
      "count": 45210
    }
  ],
  "meta": {
    "page": 1,
    "size": 50,
    "total": 1,
    "hasMore": false
  }
}
OK
GET/operators

Operators

Mobile operators. The operator name can be passed as operator on purchase.

keyscope: read

Query parameters

countryinteger
Filter by country Example: 0

Responses

GET/operators
curl -X GET 'https://simdrop.io/api/v1/operators?country=0' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": [
    {
      "id": 1,
      "name": "mts",
      "country": 0
    },
    {
      "id": 2,
      "name": "beeline",
      "country": 0
    }
  ],
  "meta": {
    "page": 1,
    "size": 2,
    "total": 2,
    "hasMore": false
  }
}
OK
GET/prices

Purchase prices

Offers for a service — across all countries or for one. Each offer contains price tiers (prices[]) with a priceId for purchase, available count and SMS deliverability. Tiers with requiredRank above your rank are marked available=false.

keyscope: read

Query parameters

servicestringrequired
Service code Example: tg
countryinteger
Country ID Example: 0
verificationTypestringsms | call
Only SMS or only call prices
currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

GET/prices
curl -X GET 'https://simdrop.io/api/v1/prices?service=tg&country=0' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": [
    {
      "service": "tg",
      "country": 0,
      "count": 1240,
      "deliverability": 87.5,
      "recommended": true,
      "blocked": false,
      "prices": [
        {
          "id": 88102,
          "price": 25.5,
          "currency": "RUB",
          "count": 640,
          "verificationType": "sms",
          "requiredRank": 0,
          "available": true
        },
        {
          "id": 88103,
          "price": 21,
          "currency": "RUB",
          "count": 600,
          "verificationType": "sms",
          "requiredRank": 2,
          "available": false,
          "unavailableOperators": [
            "tele2"
          ]
        },
        {
          "id": 88110,
          "price": 31,
          "currency": "RUB",
          "count": 120,
          "verificationType": "call",
          "requiredRank": 0,
          "available": true
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "size": 1,
    "total": 1,
    "hasMore": false
  }
}
OK
GET/rent/services

Rent services

Services currently available for rent with the minimum price.

keyscope: read

Query parameters

searchstring
Search Example: full
pageinteger
Page number, starting at 1 Example: 1
sizeinteger
Page size (default 50, max 100) Example: 50
currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

GET/rent/services
curl -X GET 'https://simdrop.io/api/v1/rent/services' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": [
    {
      "code": "full",
      "name": "Full rent (any service)",
      "minPrice": 340,
      "currency": "RUB",
      "count": 380
    }
  ],
  "meta": {
    "page": 1,
    "size": 50,
    "total": 1,
    "hasMore": false
  }
}
OK
GET/rent/prices

Rent prices

Rent options for a service: country, duration in hours, price and count. Pass id as priceId to POST /rent.

keyscope: read

Query parameters

servicestringrequired
Service code Example: full
countryinteger
Country ID Example: 0
currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

GET/rent/prices
curl -X GET 'https://simdrop.io/api/v1/rent/prices?service=full&country=0' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": [
    {
      "id": 5121,
      "service": "full",
      "country": 0,
      "durationHours": 4,
      "price": 120,
      "currency": "RUB",
      "count": 42
    },
    {
      "id": 5122,
      "service": "full",
      "country": 0,
      "durationHours": 24,
      "price": 340,
      "currency": "RUB",
      "count": 42
    }
  ],
  "meta": {
    "page": 1,
    "size": 2,
    "total": 2,
    "hasMore": false
  }
}
OK

#Activations

Buying one-time numbers and working with them. All {id} methods also work for rent.

POST/activations

Purchase a number

Issues a number and charges its price from the balance. Choose the price one of three ways: priceId — a specific tier from GET /prices; maxPrice — the cheapest available tier at or below that price; nothing — the cheapest available tier.

keyscope: activationsspeedpurchase limit
infoAn account may have between 10 and 100 active activations depending on the loyalty rank, and one purchase at a time — a second concurrent purchase gets 409 PURCHASE_IN_PROGRESS.

Request body (JSON)

servicestringrequired
Service code Example: tg
countryintegerrequired
Country ID Example: 0
operatorstring
Operator (any by default) Example: mts
verificationTypestringsms | call
Code delivery: sms (default) or call
priceIdinteger
Price tier ID from GET /prices Example: 88102
maxPricenumber
Maximum price in the request currency Example: 30
orderIdstring
Your order reference (up to 100 chars) Example: order-7781

Responses

POST/activations
curl -X POST 'https://simdrop.io/api/v1/activations' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "service": "tg", "country": 0, "maxPrice": 30, "verificationType": "sms" }'
Response
{
  "data": {
    "id": 3051287731,
    "type": "activation",
    "status": "WAITING",
    "phone": "79991234567",
    "countryPhoneCode": "7",
    "service": "tg",
    "country": 0,
    "operator": "mts",
    "verificationType": "sms",
    "price": 25.5,
    "currency": "RUB",
    "code": null,
    "sms": [],
    "canGetAnotherSms": true,
    "replaceCount": 0,
    "createdAt": "2026-09-13T20:38:02Z",
    "activatedAt": "2026-09-13T20:38:02Z",
    "expiresAt": "2026-09-13T20:58:02Z",
    "updatedAt": "2026-09-13T20:38:02Z",
    "actions": {
      "cancel": false,
      "finish": false,
      "retry": false,
      "replace": false,
      "reactivate": false,
      "prolong": false
    }
  }
}
Number issued
GET/activations

Active activations

Activations in WAITING, WAITING_RETRY and RECEIVED (including rent), newest first.

keyscope: read

Query parameters

typestringactivation | rent
Only one-time or only rent
statusstringWAITING | WAITING_RETRY | RECEIVED
Status filter
servicestring
Service code Example: tg
countryinteger
Country ID Example: 0
pageinteger
Page number, starting at 1 Example: 1
sizeinteger
Page size (default 25, max 100) Example: 25
currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

GET/activations
curl -X GET 'https://simdrop.io/api/v1/activations' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": [
    {
      "id": 3051287731,
      "type": "activation",
      "status": "RECEIVED",
      "phone": "79991234567",
      "countryPhoneCode": "7",
      "service": "tg",
      "country": 0,
      "operator": "mts",
      "verificationType": "sms",
      "price": 25.5,
      "currency": "RUB",
      "code": "482913",
      "sms": [
        {
          "type": "sms",
          "code": "482913",
          "text": "Your Telegram code is 482913",
          "receivedAt": "2026-09-13T20:41:12Z"
        }
      ],
      "canGetAnotherSms": true,
      "replaceCount": 0,
      "createdAt": "2026-09-13T20:38:02Z",
      "activatedAt": "2026-09-13T20:38:02Z",
      "expiresAt": "2026-09-13T20:58:02Z",
      "updatedAt": "2026-09-13T20:41:12Z",
      "actions": {
        "cancel": false,
        "finish": true,
        "retry": true,
        "replace": false,
        "reactivate": false,
        "prolong": false
      }
    }
  ],
  "meta": {
    "page": 1,
    "size": 25,
    "total": 1,
    "hasMore": false
  }
}
OK
GET/activations/history

Activation history

Finished, cancelled and replaced activations with filters by date, service, country and phone.

keyscope: read

Query parameters

fromstring
From date (YYYY-MM-DD) Example: 2026-09-01
tostring
To date (YYYY-MM-DD) Example: 2026-09-13
typestringactivation | rent
Type
statusstringFINISHED | CANCELLED | REPLACED
Status filter
servicestring
Service code Example: tg
countryinteger
Country ID Example: 0
searchstring
Search by phone number Example: 7999
pageinteger
Page number, starting at 1 Example: 1
sizeinteger
Page size (default 25, max 100) Example: 25
currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

GET/activations/history
curl -X GET 'https://simdrop.io/api/v1/activations/history?from=2026-09-01&to=2026-09-13' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": [
    {
      "id": 3051287731,
      "type": "activation",
      "status": "FINISHED",
      "phone": "79991234567",
      "countryPhoneCode": "7",
      "service": "tg",
      "country": 0,
      "operator": "mts",
      "verificationType": "sms",
      "price": 25.5,
      "currency": "RUB",
      "code": "482913",
      "sms": [
        {
          "type": "sms",
          "code": "482913",
          "text": "Your Telegram code is 482913",
          "receivedAt": "2026-09-13T20:41:12Z"
        }
      ],
      "canGetAnotherSms": true,
      "replaceCount": 0,
      "createdAt": "2026-09-13T20:38:02Z",
      "activatedAt": "2026-09-13T20:38:02Z",
      "expiresAt": "2026-09-13T20:58:02Z",
      "updatedAt": "2026-09-13T20:41:12Z",
      "actions": {
        "cancel": false,
        "finish": false,
        "retry": false,
        "replace": false,
        "reactivate": true,
        "prolong": false
      }
    },
    {
      "id": 3051287731,
      "type": "activation",
      "status": "CANCELLED",
      "phone": "79991234567",
      "countryPhoneCode": "7",
      "service": "tg",
      "country": 0,
      "operator": "mts",
      "verificationType": "sms",
      "price": 25.5,
      "currency": "RUB",
      "code": null,
      "sms": [],
      "canGetAnotherSms": true,
      "replaceCount": 0,
      "createdAt": "2026-09-13T20:38:02Z",
      "activatedAt": "2026-09-13T20:38:02Z",
      "expiresAt": "2026-09-13T20:58:02Z",
      "updatedAt": "2026-09-13T20:38:02Z",
      "actions": {
        "cancel": false,
        "finish": false,
        "retry": false,
        "replace": false,
        "reactivate": false,
        "prolong": false
      }
    }
  ],
  "meta": {
    "page": 1,
    "size": 25,
    "total": 2,
    "hasMore": false
  }
}
OK
GET/activations/{id}

Activation status / code

Current activation state: status, latest code (code), all messages (sms[]) and available actions. The main polling method.

keyscope: read

Path parameters

idintegerrequired
Activation ID Example: 3051287731

Query parameters

currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

GET/activations/{id}
curl -X GET 'https://simdrop.io/api/v1/activations/3051287731' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": {
    "id": 3051287731,
    "type": "activation",
    "status": "RECEIVED",
    "phone": "79991234567",
    "countryPhoneCode": "7",
    "service": "tg",
    "country": 0,
    "operator": "mts",
    "verificationType": "sms",
    "price": 25.5,
    "currency": "RUB",
    "code": "482913",
    "sms": [
      {
        "type": "sms",
        "code": "482913",
        "text": "Your Telegram code is 482913",
        "receivedAt": "2026-09-13T20:41:12Z"
      }
    ],
    "canGetAnotherSms": true,
    "replaceCount": 0,
    "createdAt": "2026-09-13T20:38:02Z",
    "activatedAt": "2026-09-13T20:38:02Z",
    "expiresAt": "2026-09-13T20:58:02Z",
    "updatedAt": "2026-09-13T20:41:12Z",
    "actions": {
      "cancel": false,
      "finish": true,
      "retry": true,
      "replace": false,
      "reactivate": false,
      "prolong": false
    }
  }
}
OK
GET/activations/{id}/sms

All SMS for an activation

Full list of received messages (SMS and calls). For rent — all messages for the period.

keyscope: read

Path parameters

idintegerrequired
Activation ID Example: 3051287731

Responses

GET/activations/{id}/sms
curl -X GET 'https://simdrop.io/api/v1/activations/3051287731/sms' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": [
    {
      "type": "sms",
      "code": "482913",
      "text": "Your Telegram code is 482913",
      "receivedAt": "2026-09-13T20:41:12Z"
    },
    {
      "type": "sms",
      "code": "117733",
      "text": "Your Telegram code is 117733",
      "receivedAt": "2026-09-13T20:47:40Z"
    }
  ],
  "meta": {
    "page": 1,
    "size": 2,
    "total": 2,
    "hasMore": false
  }
}
OK
DELETE/activations/{id}

Cancel an activation

Cancels with a full refund. Available 2 minutes after purchase while no code has arrived. For rent — within the 2–20 minute window without SMS.

keyscope: activations

Path parameters

idintegerrequired
Activation ID Example: 3051287731

Query parameters

currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

DELETE/activations/{id}
curl -X DELETE 'https://simdrop.io/api/v1/activations/3051287731' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": {
    "id": 3051287731,
    "type": "activation",
    "status": "CANCELLED",
    "phone": "79991234567",
    "countryPhoneCode": "7",
    "service": "tg",
    "country": 0,
    "operator": "mts",
    "verificationType": "sms",
    "price": 25.5,
    "currency": "RUB",
    "code": null,
    "sms": [],
    "canGetAnotherSms": true,
    "replaceCount": 0,
    "createdAt": "2026-09-13T20:38:02Z",
    "activatedAt": "2026-09-13T20:38:02Z",
    "expiresAt": "2026-09-13T20:58:02Z",
    "updatedAt": "2026-09-13T20:38:02Z",
    "actions": {
      "cancel": false,
      "finish": false,
      "retry": false,
      "replace": false,
      "reactivate": false,
      "prolong": false
    }
  }
}
Cancelled, refunded
POST/activations/{id}/finish

Finish an activation

Confirms successful use of the number after the code arrived (status FINISHED). For rent — early termination without a refund.

keyscope: activations

Path parameters

idintegerrequired
Activation ID Example: 3051287731

Query parameters

currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

POST/activations/{id}/finish
curl -X POST 'https://simdrop.io/api/v1/activations/3051287731/finish' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": {
    "id": 3051287731,
    "type": "activation",
    "status": "FINISHED",
    "phone": "79991234567",
    "countryPhoneCode": "7",
    "service": "tg",
    "country": 0,
    "operator": "mts",
    "verificationType": "sms",
    "price": 25.5,
    "currency": "RUB",
    "code": "482913",
    "sms": [
      {
        "type": "sms",
        "code": "482913",
        "text": "Your Telegram code is 482913",
        "receivedAt": "2026-09-13T20:41:12Z"
      }
    ],
    "canGetAnotherSms": true,
    "replaceCount": 0,
    "createdAt": "2026-09-13T20:38:02Z",
    "activatedAt": "2026-09-13T20:38:02Z",
    "expiresAt": "2026-09-13T20:58:02Z",
    "updatedAt": "2026-09-13T20:41:12Z",
    "actions": {
      "cancel": false,
      "finish": false,
      "retry": false,
      "replace": false,
      "reactivate": true,
      "prolong": false
    }
  }
}
Finished
POST/activations/{id}/retry

Request another SMS

Puts the activation back into waiting for the next message on the same number (if canGetAnotherSms=true). Free.

keyscope: activations

Path parameters

idintegerrequired
Activation ID Example: 3051287731

Query parameters

currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

POST/activations/{id}/retry
curl -X POST 'https://simdrop.io/api/v1/activations/3051287731/retry' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": {
    "id": 3051287731,
    "type": "activation",
    "status": "WAITING_RETRY",
    "phone": "79991234567",
    "countryPhoneCode": "7",
    "service": "tg",
    "country": 0,
    "operator": "mts",
    "verificationType": "sms",
    "price": 25.5,
    "currency": "RUB",
    "code": "482913",
    "sms": [
      {
        "type": "sms",
        "code": "482913",
        "text": "Your Telegram code is 482913",
        "receivedAt": "2026-09-13T20:41:12Z"
      }
    ],
    "canGetAnotherSms": true,
    "replaceCount": 0,
    "createdAt": "2026-09-13T20:38:02Z",
    "activatedAt": "2026-09-13T20:38:02Z",
    "expiresAt": "2026-09-13T20:58:02Z",
    "updatedAt": "2026-09-13T20:41:12Z",
    "actions": {
      "cancel": false,
      "finish": true,
      "retry": true,
      "replace": false,
      "reactivate": false,
      "prolong": false
    }
  }
}
Waiting for the next SMS
POST/activations/{id}/replace

Replace the number

Issues a different number instead of the current one for free (anti-ban). Only in WAITING, 2 minutes after purchase, at most 3 times. The old activation becomes REPLACED; the response is the new activation with a new id.

keyscope: activationsspeedpurchase limit

Path parameters

idintegerrequired
Activation ID Example: 3051287731

Query parameters

currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

POST/activations/{id}/replace
curl -X POST 'https://simdrop.io/api/v1/activations/3051287731/replace' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": {
    "id": 3051287990,
    "type": "activation",
    "status": "WAITING",
    "phone": "79995550011",
    "countryPhoneCode": "7",
    "service": "tg",
    "country": 0,
    "operator": "mts",
    "verificationType": "sms",
    "price": 25.5,
    "currency": "RUB",
    "code": null,
    "sms": [],
    "canGetAnotherSms": true,
    "replaceCount": 1,
    "createdAt": "2026-09-13T20:38:02Z",
    "activatedAt": "2026-09-13T20:38:02Z",
    "expiresAt": "2026-09-13T20:58:02Z",
    "updatedAt": "2026-09-13T20:38:02Z",
    "actions": {
      "cancel": false,
      "finish": false,
      "retry": false,
      "replace": false,
      "reactivate": false,
      "prolong": false
    }
  }
}
New activation
GET/activations/{id}/reactivate/options

Reactivation price

Whether the number can receive SMS again (for finished activations) and how much it costs.

keyscope: read

Path parameters

idintegerrequired
Activation ID Example: 3051287731

Query parameters

currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

GET/activations/{id}/reactivate/options
curl -X GET 'https://simdrop.io/api/v1/activations/3051287731/reactivate/options' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": {
    "available": true,
    "price": 12.5,
    "currency": "RUB",
    "reason": null
  }
}
OK
POST/activations/{id}/reactivate

Reactivate the number

Resumes waiting for SMS on a previously used number for a fee. The price is charged from the balance; the activation becomes WAITING again.

keyscope: activationsspeedpurchase limit

Path parameters

idintegerrequired
Activation ID Example: 3051287731

Query parameters

currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

POST/activations/{id}/reactivate
curl -X POST 'https://simdrop.io/api/v1/activations/3051287731/reactivate' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": {
    "id": 3051287731,
    "type": "activation",
    "status": "WAITING",
    "phone": "79991234567",
    "countryPhoneCode": "7",
    "service": "tg",
    "country": 0,
    "operator": "mts",
    "verificationType": "sms",
    "price": 12.5,
    "currency": "RUB",
    "code": null,
    "sms": [],
    "canGetAnotherSms": true,
    "replaceCount": 0,
    "createdAt": "2026-09-13T20:38:02Z",
    "activatedAt": "2026-09-13T21:10:00Z",
    "expiresAt": "2026-09-13T21:30:00Z",
    "updatedAt": "2026-09-13T20:38:02Z",
    "actions": {
      "cancel": false,
      "finish": false,
      "retry": false,
      "replace": false,
      "reactivate": false,
      "prolong": false
    }
  }
}
Waiting for SMS

#Rent

Renting a number for hours or days with all SMS received. A rented number is an activation with type=rent: status, SMS, cancel and finish go through /activations/{id}.

POST/rent

Rent a number

Issues a number for the given duration. priceId comes from GET /rent/prices; if omitted, it is resolved by service, country and duration.

keyscope: rentspeedpurchase limit

Request body (JSON)

servicestringrequired
Service code (full — any service) Example: full
countryintegerrequired
Country ID Example: 0
durationHoursintegerrequired
Rent duration in hours (from GET /rent/prices) Example: 24
priceIdinteger
Rent price ID Example: 5122
operatorstring
Operator Example: mts

Responses

POST/rent
curl -X POST 'https://simdrop.io/api/v1/rent' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "service": "full", "country": 0, "durationHours": 24, "priceId": 5122 }'
Response
{
  "data": {
    "id": 3051290002,
    "type": "rent",
    "status": "WAITING",
    "phone": "79991234567",
    "countryPhoneCode": "7",
    "service": "full",
    "country": 0,
    "operator": "mts",
    "verificationType": "sms",
    "price": 340,
    "currency": "RUB",
    "code": null,
    "sms": [],
    "canGetAnotherSms": true,
    "replaceCount": 0,
    "createdAt": "2026-09-13T20:38:02Z",
    "activatedAt": "2026-09-13T20:38:02Z",
    "expiresAt": "2026-09-14T20:38:02Z",
    "updatedAt": "2026-09-13T20:38:02Z",
    "actions": {
      "cancel": false,
      "finish": true,
      "retry": false,
      "replace": false,
      "reactivate": false,
      "prolong": true
    },
    "rentDurationHours": 24
  }
}
Number rented
GET/rent

Active rents

Same as GET /activations?type=rent.

keyscope: read

Query parameters

servicestring
Service code Example: full
countryinteger
Country ID Example: 0
pageinteger
Page number, starting at 1 Example: 1
sizeinteger
Page size (default 25, max 100) Example: 25
currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

GET/rent
curl -X GET 'https://simdrop.io/api/v1/rent' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": [
    {
      "id": 3051290002,
      "type": "rent",
      "status": "WAITING",
      "phone": "79991234567",
      "countryPhoneCode": "7",
      "service": "full",
      "country": 0,
      "operator": "mts",
      "verificationType": "sms",
      "price": 340,
      "currency": "RUB",
      "code": null,
      "sms": [],
      "canGetAnotherSms": true,
      "replaceCount": 0,
      "createdAt": "2026-09-13T20:38:02Z",
      "activatedAt": "2026-09-13T20:38:02Z",
      "expiresAt": "2026-09-14T20:38:02Z",
      "updatedAt": "2026-09-13T20:38:02Z",
      "actions": {
        "cancel": false,
        "finish": true,
        "retry": false,
        "replace": false,
        "reactivate": false,
        "prolong": true
      },
      "rentDurationHours": 24
    }
  ],
  "meta": {
    "page": 1,
    "size": 25,
    "total": 1,
    "hasMore": false
  }
}
OK
GET/activations/{id}/prolong/options

Extension options

Available rent extension durations and their prices.

keyscope: read

Path parameters

idintegerrequired
Activation ID Example: 3051290002

Query parameters

currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Responses

GET/activations/{id}/prolong/options
curl -X GET 'https://simdrop.io/api/v1/activations/3051290002/prolong/options' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": {
    "available": true,
    "options": [
      {
        "durationHours": 4,
        "price": 90,
        "currency": "RUB"
      },
      {
        "durationHours": 24,
        "price": 300,
        "currency": "RUB"
      }
    ],
    "reason": null
  }
}
OK
POST/activations/{id}/prolong

Extend rent

Extends the rent by a duration from GET …/prolong/options; the price is charged from the balance.

keyscope: rentspeedpurchase limit

Path parameters

idintegerrequired
Activation ID Example: 3051290002

Query parameters

currencystringRUB | USD
Currency of amounts in the response; defaults to the key currency

Request body (JSON)

durationHoursinteger
Extension in hours (optional when there is a single option) Example: 24

Responses

POST/activations/{id}/prolong
curl -X POST 'https://simdrop.io/api/v1/activations/3051290002/prolong' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "durationHours": 24 }'
Response
{
  "data": {
    "id": 3051290002,
    "type": "rent",
    "status": "WAITING",
    "phone": "79991234567",
    "countryPhoneCode": "7",
    "service": "full",
    "country": 0,
    "operator": "mts",
    "verificationType": "sms",
    "price": 340,
    "currency": "RUB",
    "code": null,
    "sms": [],
    "canGetAnotherSms": true,
    "replaceCount": 0,
    "createdAt": "2026-09-13T20:38:02Z",
    "activatedAt": "2026-09-13T20:38:02Z",
    "expiresAt": "2026-09-15T20:38:02Z",
    "updatedAt": "2026-09-13T20:38:02Z",
    "actions": {
      "cancel": false,
      "finish": true,
      "retry": false,
      "replace": false,
      "reactivate": false,
      "prolong": true
    },
    "rentDurationHours": 48
  }
}
Extended

#Utility

GET/ping

Health check

The only method without a key: API availability and server time (UTC) for clock sync.

publicno key

Responses

GET/ping
curl -X GET 'https://simdrop.io/api/v1/ping' \
  -H 'X-Api-Key: sdk_YOUR_API_KEY'
Response
{
  "data": {
    "ok": true,
    "time": "2026-09-13T20:00:00Z",
    "version": "v1"
  }
}
OK