APIs

LegitSMS Developer API Documentation

Welcome to the LegitSMS V2 API. This RESTful interface allows developers to integrate our high-quality SMS verification services directly into their own software, bots, or websites. You can programmatically purchase numbers, check stock in real-time, and manage SMS activations with ease.

Base URL

All requests must be made to:

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

Authentication (Required)

Every request requires your unique API Key to identify your account and wallet. You can find your key in the dashboard above.

• Method 1 (Header): X-API-KEY: sk_live_... (Recommended)
• Method 2 (Parameter): ?api_key=sk_live_...

Core Parameters

Most endpoints rely on these standard IDs:

• service: The numeric ID of the App/Service (e.g., 1012 for WhatsApp). Use the /services endpoint to get the full list.
• country: The numeric ID of the Country (e.g., 1 for USA). Use the /prices endpoint to see which countries are in stock.
• order_id: The unique ID received after placing an order. Used to check status or cancel.

1. Get Balance

Check your wallet balance.

• Endpoint: GET /balance
• Parameters: api_key

✅ Success Response:

JSON

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

❌ Error Example (Invalid Key):

• Code: 401 Unauthorized

JSON

{
  "code": "invalid_key",
  "message": "Invalid API Key",
  "data": { "status": 401 }
}

2. Get Services

Get a list of all available services (Apps) and their IDs.

• Endpoint: GET /services
• Parameters: None

✅ Success Response:

JSON

{
  "status": "success",
  "services": [
    { "id": "924", "name": "Tiktok/Douyin" },
    { "id": "1012", "name": "Whatsapp" }
  ]
}

3. Get Prices & Stock

Get live prices, stock, and success rates for a service.

• Endpoint: GET /prices
• Parameters: api_key, service (e.g., 1012)

✅ Success Response:

JSON

{
  "status": "success",
  "prices": {
    "1": {
      "country": "United States",
      "id": 1,
      "cost": 2.66,
      "count": 3868,
      "rate": 56
    }
  }
}

❌ Error Example (Service Not Found / Empty):

• Code: 400 Bad Request

JSON

{
  "code": "missing_params",
  "message": "Service code required",
  "data": { "status": 400 }
}

4. Order a Number

Purchase a number.

• Endpoint: POST /order
• Parameters: api_key, country, service

✅ Success Response:

JSON

{
  "status": "success",
  "order_id": "12345678",
  "phone": "12025550199",
  "cost": 2.66,
  "msg": "Waiting for SMS"
}

❌ Error Example (Out of Stock):

• Code: 404 Not Found

JSON

{
  "code": "no_stock",
  "message": "Out of stock",
  "data": { "status": 404 }
}

❌ Error Example (Low Balance):

• Code: 402 Payment Required

JSON

{
  "code": "insufficient_funds",
  "message": "Balance low",
  "data": { "status": 402 }
}

5. Check Status

Check for SMS code arrival.

• Endpoint: GET /status
• Parameters: api_key, order_id

✅ Success Response (Code Received):

JSON

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

⏳ Pending Response (Waiting):

JSON

{ "status": "STATUS_WAIT_CODE" }

❌ Error Example (Order Not Found):

• Code: 404 Not Found

JSON

{
  "code": "not_found",
  "message": "Order not found",
  "data": { "status": 404 }
}

6. Cancel Order

Cancel an order and get a refund.

• Endpoint: POST /set_status
• Parameters: api_key, order_id, status (Value: 8)

✅ Success Response:

JSON

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

❌ Error Example (Code Already Received):

• Code: 400 Bad Request

JSON

{
  "code": "cannot_cancel",
  "message": "Code already received",
  "data": { "status": 400 }
}

❌ Error Example (Too Late / Expired):

• Code: 400 Bad Request

JSON

{
  "code": "cancel_failed",
  "message": "Order expired or already finished",
  "data": { "status": 400 }
}