Developer API Documentation

Getting Started

This API lets a developer or tester get a temporary virtual phone number, read the SMS verification code sent to it, and close the session - without using a real phone. It is for staging tests, automated sign-up flows, and bulk verification where a separate number is allowed by the service being signed up to. In brief: get an API key, check the price for a service and country, lease a number, paste it into the sign-up form, poll for the code, and cancel or close the session when done. Acceptance is decided by the service you are signing up to. This API does not promise that any service will accept a particular number type, and a short-term number should not be the only way back into a recovery-critical account.

Phone numbers, codes, prices, and availability counts in the examples on this page are examples only, not live stock or pricing. Check the offers endpoint for the current price and availability for your service and country.

All API communication is executed over secure HTTPS protocols. Request headers require Accept: application/json and Content-Type: application/json schemas.

Production Base API Endpoint:

https://api.smsotps.com/api/

Authentication

Include your personal secure developer key within the request headers. Generate, rotate, or revoke keys at any time via your Profile Portal.

Required Custom HTTP Header:

X-API-KEY: YOUR_API_KEY_HERE

Quickstart: key to first code

Log in to the dashboard and generate an API key from your profile. Keep the key secret - do not share it, and do not put it in client-side code or a public repository. Rotate or revoke it from your profile if it is exposed.
Check the price and availability for your service and country with the offers endpoint.
Lease a number with the order endpoint, using the service shortcode and country ID from the lookup files.
Paste the returned number into the sign-up form and request the code once.
Poll the number-status endpoint until the code arrives or the lease window ends (20 minutes). Keep your request rate within the limits described below.
When the code is received, the order is complete and can no longer be cancelled. If no code has arrived, you can cancel the order before the lease window ends, as described in the cancellation section.

Balance & Ledger

Get Balance Details

GET

https://api.smsotps.com/api/balance

GET https://api.smsotps.com/api/balance
X-API-KEY: YOUR_API_KEY_HERE

import requests

res = requests.get(
    "https://api.smsotps.com/api/balance",
    headers={
        "Accept": "application/json",
        "X-API-KEY": "YOUR_API_KEY_HERE"
    }
)
print(res.json())

fetch("https://api.smsotps.com/api/balance", {
  headers: {
    "Accept": "application/json",
    "X-API-KEY": "YOUR_API_KEY_HERE"
  }
})
.then(res => res.json())
.then(console.log);

Response Example (200 Success):

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

About the provider sections

The provider A and provider B sections below follow the same order flow and each has its own countries and services lookup files, linked in their sections. Provider D lookup files are published for reference, but provider D is currently switched off and its API routes answer 404. The provider C section covers link-based bulk orders only: those orders cannot be cancelled once placed, and there are no provider C countries or services lookup files. The provider for a standard order is assigned by the system based on availability and price - you order against a service and country, not against a specific provider.

Get Countries List (Provider A)

Query Supported Carrier Countries

GET

/provider_a_countries.json

GET https://smsotps.com/provider_a_countries.json

import requests

res = requests.get(
    "https://smsotps.com/provider_a_countries.json",
    headers={"Accept": "application/json"}
)
print(res.json())

fetch("https://smsotps.com/provider_a_countries.json", {
  headers: { "Accept": "application/json" }
})
.then(res => res.json())
.then(console.log);

Response Example (200 Success):

{
  "16": {
    "name": "United Kingdom",
    "operators": ["any", "o2", "ee", "lebara", "three", "vodafone"]
  },
  "187": {
    "name": "USA",
    "operators": ["any", "tmobile", "at_t", "verizon"]
  }
}

Get Services List (Provider A)

Query Service Lookup Mapping

GET

/provider_a_services.json

GET https://smsotps.com/provider_a_services.json

import requests

res = requests.get(
    "https://smsotps.com/provider_a_services.json",
    headers={"Accept": "application/json"}
)
print(res.json())

fetch("https://smsotps.com/provider_a_services.json", {
  headers: { "Accept": "application/json" }
})
.then(res => res.json())
.then(console.log);

Response Example (200 Success):

{
  "fb": "facebook",
  "ig": "Instagram+Threads",
  "wa": "Whatsapp",
  "tg": "Telegram",
  "go": "Google,youtube,Gmail"
}

Get SMS Offers (Provider A)

Query Active SMS Prices

GET

https://api.smsotps.com/api/p_a/offers/{service}/{country}

GET https://api.smsotps.com/api/p_a/offers/fb/1

import requests
res = requests.get("https://api.smsotps.com/api/p_a/offers/fb/1")
print(res.json())

fetch("https://api.smsotps.com/api/p_a/offers/fb/1")
  .then(res => res.json())
  .then(console.log);

Response Parameters:

price: Float. The actual purchase cost per number lease.
available: Integer. The current count of active available numbers (pieces/pcs) ready for instant leasing.
operator: String. The carrier network provider (e.g. "any" or carrier key).

Response Example (200 Success):

{
  "status": "success",
  "offers": [
    {
      "operator": "any",
      "price": 0.08,
      "available": 3540
    }
  ]
}

Order SMS Number (Provider A)

Lease Number (Provider A)

POST

https://api.smsotps.com/api/order-number

POST Parameters (JSON Body):

provider: String, required. Exactly "provider_a"
service: String, required. The service shortcode (e.g. "fb")
country: Integer, required. The country ID (e.g. 1)
operator: String, optional. Carrier operator code. Omit (or set to "any") to let the system pick any available carrier.
max_price: Float, optional. Maximum price budget per number. Omit to accept any price.

Example — Required params only (any operator, any price):

POST https://api.smsotps.com/api/order-number
X-API-KEY: YOUR_API_KEY_HERE
Content-Type: application/json

{
  "provider": "provider_a",
  "service": "fb",
  "country": 1
}

Example — With operator & max price (optional):

POST https://api.smsotps.com/api/order-number
X-API-KEY: YOUR_API_KEY_HERE
Content-Type: application/json

{
  "provider": "provider_a",
  "service": "fb",
  "country": 1,
  "operator": "o2",
  "max_price": 0.15
}

Response Example (200 Success):

{
  "id": 98514,
  "number": "+17799042123",
  "status": "active",
  "price": 0.08,
  "operator": "any",
  "created_at": "2026-05-17T22:31:00Z"
}

Check Lease Status (Provider A)

Query Lease Order

GET

https://api.smsotps.com/api/number-status/{id}

GET https://api.smsotps.com/api/number-status/98514
X-API-KEY: YOUR_API_KEY_HERE

import requests
res = requests.get(
    "https://api.smsotps.com/api/number-status/98514",
    headers={"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
)
print(res.json())

fetch("https://api.smsotps.com/api/number-status/98514", {
  headers: {"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
})
.then(res => res.json())
.then(console.log);

Response Example (200 Success - Code Received):

{
  "id": 98514,
  "number": "+17799042123",
  "status": "completed",
  "sms_code": "845120",
  "full_text": "Your Facebook confirmation code is 845120"
}

Cancellations, Expiry and Refunds

A leased number stays active for its lease window (usually 20 minutes, set per provider).
For standard one-time activation orders: you can cancel an order between 2 and 20 minutes after purchase, as long as no SMS code has arrived. The full order amount is refunded to your balance immediately. Once a code has arrived, cancellation is no longer possible. Link-based bulk account orders are not covered by automatic or self-service cancellation refunds.
For standard one-time activation orders: if no SMS code arrives before the lease window ends, the order expires and the charge is automatically refunded to your balance.
Once a code has arrived, the order can no longer be cancelled or refunded.

Cancel Lease Order (Provider A)

Cancel Order

POST

https://api.smsotps.com/api/cancel-number/{id}

POST https://api.smsotps.com/api/cancel-number/98514
X-API-KEY: YOUR_API_KEY_HERE

import requests
res = requests.post(
    "https://api.smsotps.com/api/cancel-number/98514",
    headers={"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
)
print(res.json())

fetch("https://api.smsotps.com/api/cancel-number/98514", {
  method: "POST",
  headers: {"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
})
.then(res => res.json())
.then(console.log);

Resend SMS OTP (Provider A)

Resend Request

POST

https://api.smsotps.com/api/resend-sms/{id}

POST https://api.smsotps.com/api/resend-sms/98514
X-API-KEY: YOUR_API_KEY_HERE

import requests
res = requests.post(
    "https://api.smsotps.com/api/resend-sms/98514",
    headers={"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
)
print(res.json())

fetch("https://api.smsotps.com/api/resend-sms/98514", {
  method: "POST",
  headers: {"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
})
.then(res => res.json())
.then(console.log);

Get Countries List (Provider B)

Query Supported Carrier Countries

GET

/provider_b_countries.json

GET https://smsotps.com/provider_b_countries.json

import requests

res = requests.get(
    "https://smsotps.com/provider_b_countries.json",
    headers={"Accept": "application/json"}
)
print(res.json())

fetch("https://smsotps.com/provider_b_countries.json", {
  headers: { "Accept": "application/json" }
})
.then(res => res.json())
.then(console.log);

Response Example (200 Success):

{
  "16": {
    "name": "United Kingdom",
    "operators": ["any", "o2", "ee", "lebara", "three", "vodafone"]
  },
  "187": {
    "name": "USA",
    "operators": ["any", "tmobile", "at_t", "verizon"]
  }
}

Get Services List (Provider B)

Query Service Lookup Mapping

GET

/provider_b_services.json

GET https://smsotps.com/provider_b_services.json

import requests

res = requests.get(
    "https://smsotps.com/provider_b_services.json",
    headers={"Accept": "application/json"}
)
print(res.json())

fetch("https://smsotps.com/provider_b_services.json", {
  headers: { "Accept": "application/json" }
})
.then(res => res.json())
.then(console.log);

Response Example (200 Success):

{
  "fb": "facebook",
  "ig": "Instagram+Threads",
  "wa": "Whatsapp",
  "tg": "Telegram",
  "go": "Google,youtube,Gmail"
}

Get SMS Offers (Provider B)

Query Active SMS Prices

GET

https://api.smsotps.com/api/p_b/offers/{service}/{country}

GET https://api.smsotps.com/api/p_b/offers/fb/1

import requests
res = requests.get("https://api.smsotps.com/api/p_b/offers/fb/1")
print(res.json())

fetch("https://api.smsotps.com/api/p_b/offers/fb/1")
  .then(res => res.json())
  .then(console.log);

Response Parameters:

price: Float. The actual purchase cost per number lease.
available: Integer. The current count of active available numbers (pieces/pcs) ready for instant leasing.
operator: String. The carrier network provider (e.g. "any" or carrier key).

Response Example (200 Success):

{
  "status": "success",
  "offers": [
    {
      "operator": "any",
      "price": 0.09,
      "available": 1420
    }
  ]
}

Order SMS Number (Provider B)

Lease Number (Provider B)

POST

https://api.smsotps.com/api/order-number

POST Parameters (JSON Body):

provider: String, required. Exactly "provider_b"
service: String, required. The service shortcode (e.g. "fb")
country: Integer, required. The country ID (e.g. 1)
operator: String, optional. Carrier operator code. Omit (or set to "any") to let the system pick any available carrier.
max_price: Float, optional. Maximum price budget per number. Omit to accept any price.

Example — Required params only (any operator, any price):

POST https://api.smsotps.com/api/order-number
X-API-KEY: YOUR_API_KEY_HERE
Content-Type: application/json

{
  "provider": "provider_b",
  "service": "fb",
  "country": 1
}

Example — With operator & max price (optional):

POST https://api.smsotps.com/api/order-number
X-API-KEY: YOUR_API_KEY_HERE
Content-Type: application/json

{
  "provider": "provider_b",
  "service": "fb",
  "country": 1,
  "operator": "tmobile",
  "max_price": 0.15
}

Response Example (200 Success):

{
  "id": 98515,
  "number": "+17799042125",
  "status": "active",
  "price": 0.09,
  "operator": "any",
  "created_at": "2026-05-17T22:35:00Z"
}

Check Lease Status (Provider B)

Query Lease Order

GET

https://api.smsotps.com/api/number-status/{id}

GET https://api.smsotps.com/api/number-status/98515
X-API-KEY: YOUR_API_KEY_HERE

import requests
res = requests.get(
    "https://api.smsotps.com/api/number-status/98515",
    headers={"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
)
print(res.json())

fetch("https://api.smsotps.com/api/number-status/98515", {
  headers: {"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
})
.then(res => res.json())
.then(console.log);

Response Example (200 Success - Code Received):

{
  "id": 98515,
  "number": "+17799042125",
  "status": "completed",
  "sms_code": "410294",
  "full_text": "Your Facebook verification code is 410294"
}

Cancel Lease Order (Provider B)

Cancel Order

POST

https://api.smsotps.com/api/cancel-number/{id}

POST https://api.smsotps.com/api/cancel-number/98515
X-API-KEY: YOUR_API_KEY_HERE

import requests
res = requests.post(
    "https://api.smsotps.com/api/cancel-number/98515",
    headers={"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
)
print(res.json())

fetch("https://api.smsotps.com/api/cancel-number/98515", {
  method: "POST",
  headers: {"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
})
.then(res => res.json())
.then(console.log);

Resend SMS OTP (Provider B)

Resend Request

POST

https://api.smsotps.com/api/resend-sms/{id}

POST https://api.smsotps.com/api/resend-sms/98515
X-API-KEY: YOUR_API_KEY_HERE

import requests
res = requests.post(
    "https://api.smsotps.com/api/resend-sms/98515",
    headers={"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
)
print(res.json())

fetch("https://api.smsotps.com/api/resend-sms/98515", {
  method: "POST",
  headers: {"Accept": "application/json", "X-API-KEY": "YOUR_API_KEY_HERE"}
})
.then(res => res.json())
.then(console.log);

Order statuses, errors, resends and limits

This section documents the standard behavior and default limits of the current API implementation. Exact limits can vary per account; the error messages returned on your own requests are authoritative for your account.

Order statuses

STATUS_WAIT_CODE - the number is leased and waiting for the SMS code.
STATUS_OK:code - the code has arrived; the code follows the colon.
STATUS_CANCEL / STATUS_CANCELED - the order was cancelled or expired.

Error responses

401 - missing or invalid API key. Check the X-API-KEY header.
405 - wrong HTTP method or wrong URL for the endpoint.
422 - validation error, such as a missing service or country parameter. Check the payload.
429 - rate limit reached. Slow down; see the limits below.
500 - an error on our side. Retry, and contact support if it continues.

Resending a code

A resend is allowed only while the number is still within its 20-minute lease window and has not been cancelled. A successful resend puts the order back into the waiting state; any codes already received are kept, and the newest code is the one to use. The provider can decline a resend, in which case the API returns an error and the order is unchanged.

Rate limits

Authenticated accounts have a default overall limit of 120 requests per minute. Order and cancel operations are limited separately to 60 per minute per account by default, and order-status and other data reads to 60 per minute per IP address. Exceeding a limit returns a 429 error; wait before retrying. Contact support if your integration needs a higher order quota.

Key safety and support

Generate one key per integration where possible, store it server-side only, rotate it if it is exposed, and revoke keys that are no longer used - rotation and revocation are available from your profile and via the API. Never share a key with another person or service. For API errors, contact support at support@smsotps.com or Telegram @sms_otpsbot with the endpoint, order ID, and timestamp.

Get Services & Options (Provider C)

Get Supported Options

GET

Get a detailed nested directory listing all services and countries available under the Link Provider C portal.

https://api.smsotps.com/api/p_c/options

GET https://api.smsotps.com/api/p_c/options

import requests
res = requests.get("https://api.smsotps.com/api/p_c/options")
print(res.json())

fetch("https://api.smsotps.com/api/p_c/options")
  .then(res => res.json())
  .then(console.log);

Get Link Offers

Query Active Link Offers

GET

https://api.smsotps.com/api/p_c/offers/{service}/{country}

GET https://api.smsotps.com/api/p_c/offers/fb/1

import requests
res = requests.get("https://api.smsotps.com/api/p_c/offers/fb/1")
print(res.json())

fetch("https://api.smsotps.com/api/p_c/offers/fb/1")
  .then(res => res.json())
  .then(console.log);

Response Example (200 Success):

{
  "status": "success",
  "offers": [
    {
      "price": 0.12,
      "available": 84
    }
  ]
}

Bulk Link Orders (Provider C)

Order Bulk Links

POST

Order verification link numbers in quantity bulk. Returns the matching leased lines.

https://api.smsotps.com/api/order-number

POST Parameters (JSON Body):

provider: String, exactly "provider_c"
service: Service tag (e.g. "fb")
country: Country ID (integer code, e.g. 1)
quantity: Integer, quantity bulk limit (e.g. 2)

POST https://api.smsotps.com/api/order-number
X-API-KEY: YOUR_API_KEY_HERE
Content-Type: application/json

{
  "provider": "provider_c",
  "service": "fb",
  "country": 1,
  "quantity": 2
}

import requests
res = requests.post(
    "https://api.smsotps.com/api/order-number",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "X-API-KEY": "YOUR_API_KEY_HERE"
    },
    json={
        "provider": "provider_c",
        "service": "fb",
        "country": 1,
        "quantity": 2
    }
)
print(res.json())

fetch("https://api.smsotps.com/api/order-number", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "X-API-KEY": "YOUR_API_KEY_HERE"
  },
  body: JSON.stringify({
    "provider": "provider_c",
    "service": "fb",
    "country": 1,
    "quantity": 2
  })
})
.then(res => res.json())
.then(console.log);

Response Example (200 Success - Bulk link object):

{
  "status": "success",
  "order_id": 561075,
  "numbers": [
    "+18159801235|https://sms222.us/fb-link-auth?key=qWnKz1x9c",
    "+18159801236|https://sms222.us/fb-link-auth?key=qWnKz1x9d"
  ],
  "total_price": 0.24,
  "quantity": 2
}

Developer API Documentation

API Sections

Getting Started

Authentication

Required Custom HTTP Header:

Your Developer API Key

Quickstart: key to first code

Balance & Ledger

Get Balance Details

Response Example (200 Success):

About the provider sections

Get Countries List (Provider A)

Query Supported Carrier Countries

Response Example (200 Success):

Get Services List (Provider A)

Query Service Lookup Mapping

Response Example (200 Success):

Get SMS Offers (Provider A)

Query Active SMS Prices

Response Parameters:

Response Example (200 Success):

Order SMS Number (Provider A)

Lease Number (Provider A)

Example — Required params only (any operator, any price):

Example — With operator & max price (optional):

Response Example (200 Success):

Check Lease Status (Provider A)

Query Lease Order

Response Example (200 Success - Code Received):

Cancellations, Expiry and Refunds

Cancel Lease Order (Provider A)

Cancel Order

Resend SMS OTP (Provider A)

Resend Request

Get Countries List (Provider B)

Query Supported Carrier Countries

Response Example (200 Success):

Get Services List (Provider B)

Query Service Lookup Mapping

Response Example (200 Success):

Get SMS Offers (Provider B)

Query Active SMS Prices

Response Parameters:

Response Example (200 Success):

Order SMS Number (Provider B)

Lease Number (Provider B)

Example — Required params only (any operator, any price):

Example — With operator & max price (optional):

Response Example (200 Success):

Check Lease Status (Provider B)

Query Lease Order

Response Example (200 Success - Code Received):

Cancel Lease Order (Provider B)

Cancel Order

Resend SMS OTP (Provider B)

Resend Request

Order statuses, errors, resends and limits

Order statuses

Error responses

Resending a code

Rate limits

Key safety and support

Get Services & Options (Provider C)

Get Supported Options

Get Link Offers

Query Active Link Offers

Response Example (200 Success):

Bulk Link Orders (Provider C)

Order Bulk Links

Response Example (200 Success - Bulk link object):