Login required.

API Documentation

📍 Quick Navigation

1. Server Overview

We offer three distinct servers to ensure you always have stock and the best prices. You can choose which server to use for every request.

Server ID Description Best For
1 Global / Huge Stock The lowest prices. Great for bulk accounts and common services.
2 Premium / Expensive If Server 1 and 3 doesn’t send code, try premium numbers.
3 Global / Huge Stock Massive inventory from 180+ countries. Backup if others are out of stock.

Base URL

All API requests must be sent to this endpoint:

https://legitsms.com/api/handler/?

Authentication

Every request requires your API Key. You can find your key in your account dashboard.

Parameter: api_key

2. Utility: Get Lists (Countries & Services)

Before buying a number, use these endpoints to see exactly which countries and services are available on each server.

A. Get Supported Countries

GET For Server 1

Returns a JSON Array of Objects. You must use the id field when buying a number.

https://legitsms.com/api/handler/?api_key=YOUR_API_KEY&action=getCountries&server=1

EXAMPLE RESPONSE:

[
  {
    "id": 0,
    "rus": "Россия",
    "eng": "Russia",
    "chn": "俄罗斯",
    "visible": 1
  },
  {
    "id": 187,
    "rus": "США",
    "eng": "USA",
    "chn": "美国",
    "visible": 1
  }
]

GET For Server 2

Returns a JSON Array of Objects. You must use the ID field (note uppercase “ID”).

https://legitsms.com/api/handler/?api_key=YOUR_API_KEY&action=getCountries&server=2

EXAMPLE RESPONSE:

[
  {
    "ID": 1,
    "name": "United States",
    "short_name": "US",
    "cc": "1",
    "region": "North America"
  },
  {
    "ID": 2,
    "name": "United Kingdom",
    "short_name": "UK",
    "cc": "44",
    "region": "Europe"
  }
]

GET For Server 3

Returns a JSON Object where the Key is the country slug (e.g., afghanistan). You must use this Key as the country parameter.

https://legitsms.com/api/handler/?api_key=YOUR_API_KEY&action=getCountries&server=3

EXAMPLE RESPONSE:

{
  "afghanistan": {
    "iso": { "af": 1 },
    "prefix": { "+93": 1 },
    "text_en": "Afghanistan",
    "text_ru": "Афганистан"
  },
  "usa": {
    "iso": { "us": 1 },
    "prefix": { "+1": 1 },
    "text_en": "USA",
    "text_ru": "США"
  }
}

Note: To buy a number for Afghanistan, set &country=afghanistan.

B. Get Supported Services

Retrieve the list of services available for activation. Each server requires a different identifier.

GET For Server 1

Returns a JSON object. Important: Use the code value (e.g., wa, ig) when buying.

https://legitsms.com/api/handler/?api_key=YOUR_API_KEY&action=getServices&server=1 
{
  "status": "success",
  "services": [
    { "code": "wa", "name": "Whatsapp" },
    { "code": "ig", "name": "Instagram+Threads" },
    { "code": "go", "name": "Google,youtube,Gmail" }
  ]
}

GET For Server 2

Returns a JSON Array. Important: Use the ID value (e.g., 39, 28). Do not use the name.

https://legitsms.com/api/handler/?api_key=YOUR_API_KEY&action=getServices&server=2 
[
  { "ID": 1, "name": "1688" },
  { "ID": 28, "name": "Airbnb" },
  { "ID": 39, "name": "Amazon" }
]

GET For Server 3

Returns a JSON Object. Important: Use the Key Name. This request requires a country parameter.

https://legitsms.com/api/handler/?api_key=YOUR_API_KEY&action=getServices&server=3&country=usa 
{
  "whatsapp": {
    "Category": "activation",
    "Qty": 450,
    "Price": 1.20
  },
  "amazon": {
    "Category": "activation",
    "Qty": 120,
    "Price": 0.50
  }
}

Quick Reference: Service Parameters

Server Parameter to use for service Example
1 The code string &service=wa
2 The ID number &service=39
3 The key name &service=whatsapp

3. Check Prices & Stock (getPrices)

Use this endpoint to scan the servers for live inventory and the exact calculated cost before initiating a purchase.

Request URLs

A. Single Service Check (Specific Country & App)

https://legitsms.com/api/handler/?api_key=YOUR_API_KEY&action=getPrices&server=SERVER_ID&service=SERVICE_CODE&country=COUNTRY_ID

B. Bulk Price Dump (Returns entire server catalog)

https://legitsms.com/api/handler/?api_key=YOUR_API_KEY&action=getPrices&server=SERVER_ID

Request Parameters

Parameter Description Required? Example
action Must be set to getPrices. Yes getPrices
service The service code. Optional wa
country The country ID. Optional 187
server Which server to scan. Yes 1

💡 Bulk Price Dump: If you omit the service and country parameters and only send the server parameter, the API will return a massive JSON list containing the price and stock of every country and service currently available on that server.

Response (Success)

Returns a JSON object containing your final price and current stock availability.

{
  "status": "SUCCESS",
  "server": 1,
  "service": "wa",
  "country": "187",
  "price": "5.00",
  "quantity": 526388
}

Response (Error - Out of Stock)

{
  "status": "ERROR",
  "message": "Out of stock or unavailable."
}

4. Buy a Number (getNumber)

Use this endpoint to purchase a new virtual number for a specific service and country.

Request URL

https://legitsms.com/api/handler/?api_key=YOUR_API_KEY&action=getNumber&service=SERVICE_CODE&country=COUNTRY_ID&server=SERVER_ID

Request Parameters

Parameter Description Required? Example
action Must be set to getNumber. Yes getNumber
service The service code (see list above). Yes wa (WhatsApp)
country The country ID (see list above). Yes 187 (USA)
server Which server to use (1, 2, or 3). Yes 1, 2, or 3

Response (Success)

The API returns a plain text string separated by colons (:).

ACCESS_NUMBER:ORDER_ID:PHONE_NUMBER

EXAMPLE:

ACCESS_NUMBER:12345678:15550199999
  • 12345678: This is your ORDER_ID. Save this! You need it to check for the SMS code.
  • 15550199999: This is the phone number to enter into the app/website.

Common Error Responses

NO_NUMBERS No numbers are currently available for this service/country combination.
NO_BALANCE Your wallet does not have enough funds to complete this purchase.
BAD_SERVICE The service code or ID you sent is invalid for this server.

5. Get Available Operators

Instead of guessing which carriers are online, use this to build dynamic dropdowns for your users. You can then plug any name from this list into the operator parameter of your getNumber request.

GET https://legitsms.com/api/handler/?api_key=YOUR_KEY&action=getOperators&country=187&server=1

Supported Operators Reference

Carrier names must be lowercase with no spaces.

SERVER 1

tmobile, verizon, att, sprint, o2, vodafone, ee, three

SERVER 3

tmobile, verizon, att, virtual (VOIP), lycamobile, o2, vodafone

6. Check SMS Status (getStatus)

After buying a number, you must repeatedly poll this endpoint to see if the SMS code has arrived. (Set a 3 sec delay)

GET https://legitsms.com/api-fast.php?api_key=YOUR_API_KEY&action=getStatus&id=THE_ORDER_ID
Response Meaning Action
STATUS_WAIT_CODE SMS has not arrived. Wait 5s and retry.
STATUS_OK:XXXXXX Success! XXXXXX is your code. Use the code.
STATUS_CANCEL Order expired or cancelled. Stop checking.

7. Cancel or Activate (setStatus)

Use this to refund an order (if no code arrived) or mark it as finished.

GET https://legitsms.com/api/handler/?api_key=YOUR_KEY&action=setStatus&id=ORDER_ID&status=STATUS_CODE

Status Options:

  • 8 = Cancel Number (Refunds money if no code was received).
  • 6 = Activation Complete (Marks order as finished).

Note: You must wait at least 2 minutes after purchase before you can cancel a number.

Example Workflow (Step-by-Step)

Step 1: Check Price First

GET /api/handler/?api_key=XYZ&action=getPrices&service=wa&country=187&server=1

Response: {"status": "SUCCESS", "price": "5.00", ...}

Step 2: Buy a WhatsApp Number

GET /api/handler/?api_key=XYZ&action=getNumber&service=wa&country=187&server=1

Response: ACCESS_NUMBER:550011:13215551234

Step 3: Check for Code (Polling Loop)

GET /api/handler/?api_key=XYZ&action=getStatus&id=550011

Response 1: STATUS_WAIT_CODE (Wait 5s...)

Response 2: STATUS_OK:889922 (Success!)

Step 4 (Optional): Cancel if no code arrives

GET /api/handler/?api_key=XYZ&action=setStatus&status=8&id=550011

Response: ACCESS_CANCEL (Refunded)

Live Webhooks

⚡ Event-Driven Webhooks

For high-speed automation. Instead of polling getStatus, our server pushes the SMS code to your URL the exact millisecond it arrives.

How to Setup

1

Go to your Developer API Dashboard.

2

Enter your server's listening URL in the Webhook Setup field and click Save.

3

Order numbers normally; wait for a POST request to your URL.

The Webhook Payload

Content-Type: application/json

{
  "activationId": "84729104",
  "service": "wa",
  "phone": "1234567890",
  "code": "5555",
  "status": "STATUS_OK"
}

Code Examples (Receiver)

PHP

<?php
$json = file_get_contents('php://input');
$data = json_decode($json, true);

if ($data && isset($data['code'])) {
    $sms_code = $data['code'];
    // Process code...
    http_response_code(200);
}
?>

NODE.JS / EXPRESS

app.post('/webhook', express.json(), (req, res) => {
    const { activationId, code } = req.body;
    if (code) {
        console.log(`Received code: ${code}`);
        res.status(200).send('OK');
    }
});

Complete List of Error Codes

If an API request fails, one of the following error codes will be returned. Use this table to debug your integration.

Error Code Meaning How to Fix
BAD_KEY Invalid API Key. Check your API Key in settings.
ERROR_SQL Server error. Contact Support.
NO_ACTIVATION Order ID not found. Check if you are using the correct ID.
NO_BALANCE Insufficient funds. Deposit money into your account.
NO_NUMBERS Out of stock. Try a different server or country.
BAD_SERVICE Invalid service code. Check the service list.
ERROR_WAIT_2_MINUTES Too early to cancel. Wait until the 2-minute timer finishes.

LegitSMS Rental API Documentation

Our Rental API allows you to programmatically rent phone numbers for extended periods, read incoming SMS messages, and manage active subscriptions.

Base URL: https://legitsms.com/api/rental/

GET Check Rental Price

Fetches the live, calculated price of a rental number before purchasing.

?action=rentGetPrice&country=UK&service=opt132&unit=week&time=1

Request Parameters

Parameter Type Description
api_key string Your unique account API key.
country string The 2-letter country code (e.g., UK, US).
service string The service code (e.g., opt132).
unit string Duration format: week or month.
time int Number of units (e.g., 1).

Expected Success Response

{
  "status": "success",
  "data": {
    "service": "opt132",
    "country": "UK",
    "unit": "week",
    "time": 1,
    "price": "2.50"
  }
}

GET 1. Rent a New Number

Purchases a new rental number. The cost is automatically deducted from your wallet balance.

?action=rentNumber&country=UK&service=opt132&unit=week&time=1

Request Parameters

Parameter Type Description
api_key string Your unique account API key.
country string The 2-letter country code (e.g., UK, AR).
service string The service code (e.g., opt132).
unit string Duration format: week or month.
time int Number of units (e.g., 1).

Expected Success Response

{
  "status": "success",
  "data": {
    "id": 915448,
    "number": "5491123456789",
    "cost": 2.50,
    "expires": "2026-04-09 15:30:00"
  }
}

Example Error Responses

{
  "status": "error",
  "message": "Insufficient wallet balance."
}
{
  "status": "error", 
  "message": "Service out of stock."
}

GET 2. Get SMS Inbox (Check Status)

Retrieves text messages sent to your rented number. If no message has arrived yet, it returns a pending status.

?action=rentGetStatus&id=ORDER_ID

Request Parameters

Parameter Type Description
api_key string Your account API key.
id int The exact Order ID of the rented number.

SUCCESS (SMS RECEIVED):

{
  "status": "success",
  "messages": [
    {
      "sender": "Service",
      "text": "Code: 123456",
      "date": "2026-04-02"
    }
  ]
}

PENDING (WAITING):

{
  "status": "pending",
  "message": "WAITING_FOR_SMS"
}

GET 3. Prolong (Extend) a Rental

Extends the expiration date of an active rental. The cost is automatically deducted from your wallet.

?action=rentProlong&id=914104&unit=week&count=1

Request Parameters

Parameter Type Description
id int The Order ID of the active rental.
unit string Duration format: week or month.
count int The amount of time to add (e.g., 1).

Success Response

{
  "status": "success",
  "message": "PROLONGED",
  "cost": 1.82,
  "new_end_time": "2026-04-15 05:26:00"
}

Example Error Response

(Returned if the duration type is not supported for that specific number)

{
  "status": "error",
  "message": "PROVIDER_ERROR: Incorrect duration type. Available types: week, month"
}

GET 4. Restore an Expired Number

Attempts to revive a recently expired or canceled number. If the provider still has the number available, it will be restored to your account.

?action=rentRestore&id=ORDER_ID

Request Parameters

Parameter Type Description
id int The Order ID of the expired rental.

SUCCESS RESPONSE:

{
  "status": "success",
  "message": "RESTORED",
  "cost": 2.50
}

ERROR (PERMANENTLY GONE):

{
  "status": "error",
  "message": "Time to restore has expired"
}

Appendix: Reference Codes

Use these codes for the country and service parameters when renting a new number.

Country List (Name = Code)

United Kingdom = UK
United States = USA
Argentina = AR
Germany = DE
France = FR
Canada = CA
Brazil = BR

Service List (Name = Code)

WhatsApp = opt13
Telegram = opt16
Google/Gmail = opt1
Instagram = opt132
Facebook = opt2
Twitter = opt41
Tinder = opt8

*Note: This is a partial list. See the full dynamic list via the getServices endpoint.

Appendix: Rental Reference Codes

Use these exact strings for the country and service parameters. Values are formatted as Name = Code.

Countries (Code)

Unt. Kingdom = UK
United States = US
France = FR
Germany = DE
Spain = ES
Italy = IT
Australia = AU
Mexico = MX
Brazil = BR
Philippines = PH
Indonesia = ID
Japan = JP
Romania = RO
Portugal = PT
Canada = CA
Argentina = AR
Poland = PL
Greece = GR
Albania = AL
Austria = AT
Bangladesh = BD
Belgium = BE
Bolivia = BO
Bos. and Herz. = BA
Bulgaria = BG
Cambodia = KH
Cameroon = CM
Chile = CL
Colombia = CO
Costa Rica = CR
Croatia = HR
Cyprus = CY
Czech Republic = CZ
Denmark = DK
Dominicana = DO
Estonia = EE
Finland = FI
Georgia = GE
Gibraltar = GI
Hong Kong = HK
Hungary = HU
Ireland = IE
Israel = IL
Kazakhstan = KZ
Kenya = KE
Kyrgyzstan = KG
Latvia = LV
Lithuania = LT
Macedonia = MK
Malaysia = MY
Malta = MT
Moldova = MD
Morocco = MA
Netherlands = NL
New Zealand = NZ
Pakistan = PK
Paraguay = PY
Serbia = RS
Singapore = SG
Slovakia = SK
Slovenia = SI
South Africa = ZA
Sweden = SE
Switzerland = CH
Tanzania = TZ
Thailand = TH
Turkey = TR
Ukraine = UA
Vietnam = VN

Services (Code)

OpenAI API = opt132
1cupis.ru = opt251
22bet = opt224
888casino = opt22
Abbott = opt242
Adidas & Nike = opt86
Airbnb = opt46
Alibaba = opt61
Amazon = opt44
AOL = opt10
Apple = opt131
Astropay = opt256
autocosmos.com = opt143
Avito = opt59
Badoo = opt56
BANDUS = opt209
Bazos.sk = opt138
BC GAME = opt262
Beget.com = opt187
Best Buy = opt252
bet365 = opt17
Betano = opt192
BetFair = opt25
Betmgm = opt223
Bitpanda = opt237
Blizzard = opt78
blsspain-russia.com = opt135
Bolt = opt81
Brevo = opt217
bumble = opt145
bunq = opt199
bwin = opt137
Caliente = opt267
Capital One Shopping = opt266
Careem = opt89
Casa Pariurilor = opt255
casa.it = opt148
Cash App = opt226
Cashrewards = opt214
Casino Plus = opt201
ChoTot = opt176
CityMobil = opt76
Claude = opt196
Clubhouse = opt98
CoinBase = opt112
CONTACT = opt51
Credit Karma = opt124
CrigslistApp = opt26
CupidMedia = opt157
Czech email services = opt150
Deliveroo = opt53
DenimApp = opt204
DiDi = opt92
Discord = opt45
DistroKid = opt232
Doordash = opt40
Drom.RU = opt32
Drug Vokrug = opt31
dundle = opt136
EasyPay = opt216
ENEBA = opt200
ESX = opt248
EUROBET = opt141
Facebook = opt2
FastMail = opt43
Fbet = opt215
Feeld = opt159
Fiverr = opt6
fontbet = opt139
foodora = opt189
foodpanda = opt115
Fortuna = opt221
Fotostrana = opt13
funpay = opt142
G2A.COM = opt68
Gameflip = opt77
Gamers set = opt28
GetsBet.ro = opt179
GetTaxi = opt35
GGbet = opt188
GGPokerUK = opt229
giocodigitale.it = opt85
Glovo & Raketa = opt108
goldbet.it = opt240
Google (YT/Gmail) = opt1
Google Messenger = opt259
Google Voice = opt140
GrabTaxi = opt30
Grailed = opt420
Grindr = opt110
Happn = opt155
HelloTalk = opt203
hepsiburada = opt238
Hey = opt216
Hinge = opt120
hopper = opt144
HUAWEI = opt166
ICard = opt103
idealista.com = opt165
ifood = opt55
IMO = opt111
inbox.lv = opt167
Inboxdollars = opt118
Instagram = opt16
Ipsos = opt193
IQOS = opt243
JD.com = opt94
KakaoTalk = opt71
Klarna = opt175
kleinanzeigen.de = opt152
KoronaPay = opt99
Kuper = opt97
kwiff.com = opt129
Lajumate.ro = opt195
Lalamove = opt180
LAPOSTE = opt182
LASVEGAS.RO = opt222
Lazada = opt60
Leboncoin = opt164
Line Messenger = opt37
LinkedIn = opt8
Linode = opt245
LiveScore = opt42
LocalBitcoins = opt105
Locanto.com = opt114
Lyft = opt75
Magnit = opt126
Mail.RU = opt33
Mail.ru Group = opt4
Mamba = opt100
Marktplaats = opt171
Match = opt250
maxline.by = opt219
MiChat = opt96
Microsoft = opt15
mobileDE = opt156
MOMO = opt184
Monese = opt121
MoneyLion = opt47
Monster Energy = opt254
MPSellers = opt197
MrGreen = opt211
MS Office 365 = opt7
Naver = opt73
Nectar = opt198
Neosurf = opt269
NetBet = opt95
Neteller = opt116
Netflix = opt101
NHNCloud = opt202
NHNcorp = opt177
Nico = opt119
novibet.com = opt151
OD = opt5
OfferUp = opt113
OkCupid = opt230
OKX = opt228
OLX = opt70
onet.pl = opt241
OTHER = opt19
OurTime = opt212
Outlier = opt246
OZON.ru = opt181
Paddy Power = opt109
PapaJohns = opt27
Pari.ru = opt169
Parimatch = opt3
Parions Sport = opt260
Payoneer = opt162
PayPal + Ebay = opt83
Paysafecard = opt122
PAYSEND = opt183
pm.by = opt149
POF = opt84
Pokemon Center = opt268
Profee.com = opt263
Prom.UA = opt107
Proton Mail = opt57
Publi24 = opt207
Qiwi = opt18
RadQuest = opt247
Rambler.ru = opt154
Reddit = opt265
Remitly = opt257
Revolut = opt133
ROOMSTER = opt153
Royal Canin = opt170
RusDate = opt186
Samokat = opt185
Samsung = opt174
Schibsted = opt134
Shopee = opt48
Signal = opt127
Sisal = opt38
Skelbiu = opt270
Skout = opt49
Skrill = opt117
Snapchat = opt90
SNKRDUNK = opt190
Solitaire = opt234
Steam = opt58
subito.it = opt146
SumUp = opt258
Superbet = opt249
Swagbucks = opt125
Tango = opt82
TANK.RU = opt161
Taptap = opt239
Taxi Maksim = opt74
Telegram = opt29
Tencent QQ = opt34
Ticketmaster = opt52
TikTok = opt104
Tinder = opt9
TLScontact = opt235
Toloka.ai = opt264
TopCashback = opt191
TOTOGAMING = opt220
TransferGo = opt218
TrueCaller = opt233
Truth Social = opt244
Twilio = opt66
Twitch = opt205
U By Prodia = opt160
Uber = opt72
Verse = opt39
Viber = opt11
Vinted = opt130
VK = opt69
VonageVF = opt178
VooV Meeting = opt147
Waitomo = opt213
WalletHub = opt206
Walmart = opt227
WEB.DE = opt172
WebMoney = opt24
WeChat = opt67
Weebly = opt54
Welo Data = opt261
WESTSTEIN = opt80
Whatnot = opt231
WhatsAPP = opt20
Whoosh = opt123
Wing Money = opt106
Wise = opt91
Wolt = opt163
WooPlus = opt208
X (Twitter) = opt41
X World Wallet = opt173
Yahoo = opt65
Yalla.live = opt88
Yandex = opt23
Year13 = opt236
Zalo = opt158
Zasilkovna = opt225
Zoho = opt93
ZoomInfo = opt194
Zoosk = opt253

Confirm Purchase

Service:

Country:

Amount:

Scroll to Top
×
Service: ...
Country: ...
Operator:
Amount: $0.00
Quantity:
×

Confirm Purchase

Service: ...

Country: ...

...