API Documentation

Automate number purchases and SMS verification on sms.tc. Two interfaces: a modern REST API and a drop-in SMS-Activate–compatible endpoint — point your existing SMS-Activate software at sms.tc with no code changes.

Get your API key SMS-Activate compatible

Overview

sms.tc is a multi-provider aggregator: a single API gives you access to numbers from several upstream providers, with our pricing applied. You can use whichever interface fits your stack.

REST API

JSON over HTTP. Recommended for new integrations.

https://sms.tc/api/v1

SMS-Activate

Plain-text protocol compatible with SMS-Activate clients.

https://sms.tc/stubs/handler_api.php

Get an API key

1Sign in and open your Profile → API page.
2Generate a key. It is shown once — copy and store it securely.
3Regenerating revokes the old key and emails the new one. You can optionally restrict a key to specific IP addresses and set an expiry date.

Get your API key

Authentication

Every request must include your API key. The REST API reads it from a header; the SMS-Activate endpoint reads it from the api_key query parameter.

REST

Authorization: Bearer smstc_live_xxxX-Api-Key: smstc_live_xxx

SMS-Activate

?api_key=smstc_live_xxx

Core concepts

Canonical codes

Countries use SMS-Activate numeric IDs (0=Russia, 1=Ukraine…) and services use short codes (tg, wa, ig…). Discover them via the catalog / getCountries / getServicesList endpoints.

Currency

All prices and balances are in USD (ISO 840).

Balance

Purchases are charged to your sms.tc balance. Failed or timed-out activations are refunded automatically.

SMS success rate (rate)

Offer responses may include rate: the share of our own settled activations that received an SMS (%, or null). Computed per provider + service + country, shown only with at least 10 settled activations, refreshed once a day. Use /activations/offers/providers for a per-provider breakdown.

REST API

Base URL https://sms.tc/api/v1. Authenticate with a Bearer / X-Api-Key header. Responses are JSON.

GET/activations/offersList available numbers (service → country → price/count/rate).

GET/activations/offers/providersPer-provider offers (provider, operator, price, stock, SMS success rate). Requires service + country.

POST/activationsBuy a number. Body: { service, country, operator? }.

GET/activations/{id}Get activation status + received SMS code.

GET/emailsList email activations.

POST/emailsBuy an email activation. Body: { site, domain }.

POST/emails/batchBuy email activations in bulk (count 1–10).

GET/emails/{id}Check an email activation.

DELETE/emails/{id}Cancel an email activation.

POST/emails/{id}/reorderReorder an email activation.

GET/emails/domainsList available email domains.

GET/catalog/countriesCanonical country list (SMS-Activate ids).

GET/catalog/servicesCanonical service list (short codes).

GET/catalog/pricesPrices by country/service, incl. SMS success rate (rate).

GET/rent/offersRentable services for a country + duration.

POST/rentRent a number. Body: { service, country, duration }.

GET/rent/{id}Get a rent order + its SMS.

POST/rent/{id}/prolongExtend a rent. Body: { duration }.

Example · cURL

# 1) List available numbers
curl https://sms.tc/api/v1/activations/offers \
  -H "Authorization: Bearer smstc_live_xxx"

# 2) Buy a number (Telegram, country 6)
curl -X POST https://sms.tc/api/v1/activations \
  -H "Authorization: Bearer smstc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"service":"tg","country":6}'

# 3) Check the code
curl https://sms.tc/api/v1/activations/123456 \
  -H "X-Api-Key: smstc_live_xxx"

SMS-Activate compatible API

A single endpoint at /stubs/handler_api.php dispatched by the action query parameter — mirrors the SMS-Activate protocol so existing partner software works unchanged. Responses are plain text (or JSON for the V2 / list actions).

action	Returns
getBalance	ACCESS_BALANCE:12.50
getNumber	ACCESS_NUMBER:<id>:<phone>
getNumberV2	JSON (activationId, phoneNumber, …)
getStatus	STATUS_WAIT_CODE · STATUS_OK:<code>
getStatusV2	JSON (sms, call, …)
setStatus	ACCESS_READY · ACCESS_RETRY_GET · ACCESS_ACTIVATION · ACCESS_CANCEL
getActiveActivations	JSON (active list)
getHistory	JSON (history)
getPrices	JSON (prices by country/service)
getCountries	JSON (countries)
getServicesList	JSON (services)
getOperators	JSON (operators)
getAllSms	JSON (all SMS for an activation)
finishActivation	204
cancelActivation	204
reactivate / reactivateOptions	JSON · provider-dependent
getRentNumber / getRentServicesAndCountries / serviceCountRent	JSON · provider-dependent
prolong / prolongOptions / prolongHistory	JSON · rent only

setStatus

1 report ready3 request another SMS6 complete activation8 cancel & refund

Example

# Get a number
GET https://sms.tc/stubs/handler_api.php?api_key=smstc_live_xxx&action=getNumber&service=tg&country=6
→ ACCESS_NUMBER:123456:628712345678

# Check status / code
GET https://sms.tc/stubs/handler_api.php?api_key=smstc_live_xxx&action=getStatus&id=123456
→ STATUS_OK:12345

# Complete (6) or cancel (8)
GET https://sms.tc/stubs/handler_api.php?api_key=smstc_live_xxx&action=setStatus&id=123456&status=8
→ ACCESS_CANCEL

Error codes

The SMS-Activate endpoint returns plain-text tokens (HTTP 200). The REST API returns JSON with an HTTP status and an error code.

NO_KEYAPI key is missing.

BAD_KEYAPI key is invalid, expired or not allowed for your IP.

BAD_ACTIONUnknown action parameter.

BAD_SERVICEUnknown service code.

NO_NUMBERSNo numbers available for this service/country.

NO_BALANCEInsufficient balance.

WRONG_ACTIVATION_IDActivation id is missing or malformed.

NO_ACTIVATIONActivation not found for your account.

BAD_STATUSInvalid setStatus value.

EARLY_CANCEL_DENIEDCannot cancel yet (minimum hold time not elapsed).

ACTION_NOT_AVAILABLEThis action is not available for the selected provider.

Specification

The full machine-readable spec and a getting-started guide are available below.

OpenAPI (YAML) README