LegitSMS Developer API Documentation

Please log in to view your API Key.

Welcome to the LegitSMS Public API. This API allows you to integrate our virtual number services directly into your own software, bots, or scripts.

Base URL

All requests must be made to:

https://legitsms.com/wp-json/legitsms/v1

Authentication

• Parameter: api_key
• Requirement: Must be included in the URL of every request.
• Get your Key: Log in to your account dashboard to view or generate your API Key.

1. Catalog: Get Countries

Returns a list of all available countries and their unique IDs.

• Endpoint: GET /countries
• Parameters: api_key

Success Response:

JSON

{
    "0": { "id": 0, "eng": "Russia", "rus": "Россия" },
    "6": { "id": 6, "eng": "Indonesia", "rus": "Индонезия" },
    "16": { "id": 16, "eng": "United Kingdom", "rus": "Англия" }
}

2. Catalog: Get Services

Returns a list of available services and their short codes (e.g., wa for WhatsApp).

• Endpoint: GET /services
• Parameters: api_key

Success Response:

JSON

{
    "status": "success",
    "services": [
        { "id": "wa", "name": "Whatsapp" },
        { "id": "tg", "name": "Telegram" },
        { "id": "go", "name": "Google" }
    ]
}

Common Service Codes (Cheat Sheet):

| Service | Code |

| :— | :— |

| WhatsApp | wa |

| Telegram | tg |

| Google | go |

| Facebook | fb |

| Instagram | ig |

| TikTok | lf |

| Twitter / X | tw |

3. Catalog: Get Operators (Carriers)

Returns a list of available mobile operators (carriers) for a specific country. This allows you to request numbers from a specific network (e.g., Telkomsel).

• Endpoint: GET /operators
• Parameters:
  • api_key (Required)
  • country (Required): The country ID (e.g., 6 for Indonesia).

Success Response:

JSON

{
    "status": "success",
    "country": "6",
    "operators": [
        "telkomsel",
        "indosat",
        "axis",
        "three",
        "smartfren"
    ]
}

Error Response:

JSON

{
    "code": "provider_error",
    "message": "OPERATORS_NOT_FOUND",
    "data": { "status": 400 }
}

4. Inventory: Get Price & Quantites

Check the current stock quantity and price for a specific country and service.

• Endpoint: GET /prices
• Parameters:
  • api_key (Required)
  • service (Required): Service code (e.g., wa).
  • country (Required): Country ID (e.g., 16).

Success Response:

JSON

{
    "country": "16",
    "service": "wa",
    "cost": 1.20,      // Price per number (in Rubles/USD)
    "count": 7482      // Quantity available
}

5. User: Get Balance

Check your current wallet balance.

• Endpoint: GET /balance
• Parameters: api_key

Success Response:

JSON

{
    "balance": 15.50,
    "currency": "USD"
}

6. Order: Buy Number

Purchase a number. The system automatically verifies your balance and stock availability before processing.

• Endpoint: POST /order
• Parameters:
  • api_key (Required)
  • service (Required): Service code (e.g., wa).
  • country (Required): Country ID (e.g., 16).

Success Response:

JSON

{
    "status": "success",
    "order_id": "214589001",
    "phone": "447123456789",
    "cost": 1.20,
    "msg": "Waiting for SMS"
}

Error Messages:

| JSON Code | HTTP | Meaning |

| :— | :— | :— |

| insufficient_funds | 402 | Your balance is too low to afford this number. |

| stock_error | 404 | No numbers available for this country. |

| missing_params | 400 | You forgot service or country. |

| order_failed | 400 | Provider temporarily out of stock (NO_NUMBERS). |

7. Lifecycle: Check Status (Get Code)

Check if the SMS verification code has arrived.

Recommendation: Poll this endpoint every 2-5 seconds.

• Endpoint: GET /status
• Parameters:
  • api_key (Required)
  • order_id (Required): The ID received from the /order endpoint.

Response (Waiting):

JSON

{
    "status": "STATUS_WAIT_CODE"
}

Response (Success – Code Received):

JSON

{
    "status": "STATUS_OK",
    "code": "44921"
}

Response (Cancelled):

JSON

{
    "status": "STATUS_CANCELLED"
}

8. Lifecycle: Set Status (Cancel or Finish)

Manage the active order.

• Cancel (8): Cancel the order if the code never arrived. Funds are automatically refunded.
• Finish (6): Mark the order as complete after you have successfully used the code.
• Endpoint: POST /set_status
• Parameters:
  • api_key (Required)
  • order_id (Required)
  • status (Required):
    • 8 = Cancel Order
    • 6 = Finish Order

Success Response (Cancel):

JSON

{
    "status": "success",
    "message": "Order cancelled and refunded"
}

Success Response (Finish):

JSON

{
    "status": "success",
    "message": "Order finished"
}

Error Messages:

| JSON Code | HTTP | Meaning |

| :— | :— | :— |

| already_closed | 400 | Order is already Cancelled or Finished. |

| invalid_status | 400 | Status must be 6 or 8. |

| cancel_failed | 400 | Provider refused cancellation (e.g., number was already used). |

9. Reuse Number

Purchase a new SMS verification for a number you used previously.

Note: Reuse is only possible if the number is still online and within the provider’s reuse time limit( 14 days).

• Endpoint: POST /reuse
• Parameters:
  • api_key (Required)
  • order_id (Required): The ID of the original order you want to reuse.

Success Response:

JSON

{
    "status": "success",
    "order_id": "214599999",  // New Order ID
    "phone": "447123456789",
    "cost": 1.20,
    "msg": "Reuse successful. Waiting for SMS."
}

Error Messages:

| JSON Code | HTTP | Meaning |

| :— | :— | :— |

| reuse_failed | 400 | Number is offline or time limit expired. |

| not_found | 404 | Original Order ID not found in your history. |

| insufficient_funds | 402 | Balance too low. |

Global API Error Reference

These errors can occur on any endpoint.