LegitSMS API Documentation

Welcome to the LegitSMS API. This API allows you to programmatically buy virtual phone numbers, receive SMS verification codes, and manage your activations. It is designed to be simple, fast, and compatible with most SMS-handling software.

Login required.

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.

Base URL

All API requests must be sent to this endpoint:

https://legitsms.com/api/handler

Authentication

Every request requires your API Key. Copy the key above.

• 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

For Server 1

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

• Request URL: 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
}
]

For Server 2

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

• Request URL: 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”
}
]

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.

• Request URL: 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”: “Афганистан”
},
“albania”: {
“iso”: { “al”: 1 },
“prefix”: { “+355”: 1 },
“text_en”: “Albania”,
“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

For Server 1

Returns a JSON object containing a list of services.

• Important: You must use the code value (e.g., wa, ig) when buying a number.
• Request URL: https://legitsms.com/api/handler/api_key=YOUR_API_KEY&action=getServices&server=1
• Example Response:

{
“status”: “success”,
“services”: [
{ “code”: “wa”, “name”: “Whatsapp” },
{ “code”: “ig”, “name”: “Instagram+Threads” },
{ “code”: “go”, “name”: “Google,youtube,Gmail” }
]
}

For Server 2

Returns a JSON Array of Objects.

• Important: You must use the ID value (e.g., 39, 28) when buying a number. Do not use the name.
• Request URL: https://legitsms.com/api/handler/api_key=YOUR_API_KEY&action=getServices&server=2
• Example Response:

[
{ “ID”: 1, “name”: “1688”, “favourite”: 0 },
{ “ID”: 28, “name”: “Airbnb”, “favourite”: 0 },
{ “ID”: 39, “name”: “Amazon / Amazon Web Services”, “favourite”: 0 }
]

For Server 3

Returns a JSON Object where the Key is the service name.

• Important: You must use the Key Name (e.g., whatsapp, amazon) when buying a number.
• Note: This request requires a country parameter (e.g., usa, russia).
• Request URL: https://legitsms.com/api/handler/api_key=YOUR_API_KEY&action=getServices&server=3&country=usa
• Example Response:

{
“whatsapp”: {
“Category”: “activation”,
“Qty”: 450,
“Price”: 1.20
},
“amazon”: {
“Category”: “activation”,
“Qty”: 120,
“Price”: 0.50
}
}

2. Buy a Number (getNumber)

Use this command to purchase a new virtual number for a specific service.

Request Parameters

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 code.
• 15550199999: This is the phone number to use.

Response (Errors)

• NO_NUMBERS: No numbers are currently available for this service/country.
• NO_BALANCE: Your wallet does not have enough funds.
• BAD_SERVICE: The service code you sent is invalid.

3. Check SMS Status (getStatus)

After buying a number, you must repeatedly check this endpoint to see if the SMS code has arrived.

Request Parameters

Responses

4. Cancel or Activate (setStatus)

Use this to cancel an order (if the code never arrived) or mark it as finished.

Request Parameters

Status Options

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

Responses

• ACCESS_CANCEL: The order was successfully cancelled and refunded.
• ACCESS_ACTIVATION: The order was successfully marked as complete.
• ERROR_WAIT_2_MINUTES: Wait! You cannot cancel a number immediately. You must wait at least 2 minutes after purchase before cancelling.

5. Example Workflow (Step-by-Step)

Step 1: Buy a WhatsApp number

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

Response: ACCESS_NUMBER:550011:13215551234

Step 2: Use the number

Enter 13215551234 into WhatsApp.

Step 3: Check for Code (Loop)

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

Response: STATUS_WAIT_CODE (Wait 5 seconds…)

Response: STATUS_WAIT_CODE (Wait 5 seconds…)

Response: STATUS_OK:889922

Step 4: Success!

You have the code 889922.

Step 5 (Optional): Cancel if no code arrived

If you waited 2 minutes and got no code:

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

Response: ACCESS_CANCEL

6. Complete List of Error Codes