Global SMS Verification API & Reseller SMS Provider

This is the official 1001SMS API documentation, reliable for users who want to automate SMS verification for software or apps, and for users who want to resell temporary numbers on their websites with competitive pricing, high coverage, and quality numbers.

How to generate your API key

Click Generate API Key, sign in to your account, open User Menu → API Keys, then create a new key and copy it securely (it is shown once).

Base URL

https://www.1001sms.com/api/v1

Content Type

application/json

Authorization

Bearer YOUR_API_KEY

Why Resellers Choose 1001SMS

1001SMS provides a single REST API that connects your platform to multiple independent SMS verification networks. Whether you are building a white-label reseller panel or automating OTP flows at scale, the infrastructure is designed for predictable delivery, transparent pricing, and zero operational overhead.

Multi-Provider Redundancy

3 independent networks

Route through MAIN, EXTRA, or EXTRA 2 per request. Automatic fallback keeps delivery rates high even when a single network has low stock.

Automatic Refunds

Pay only for delivered SMS

If no verification code arrives within the rental window, the full amount is credited back to your balance instantly — no support tickets required.

Wholesale Pricing

Competitive reseller rates

Access real-time cost and resale prices across all providers so you can set transparent margins and surface live pricing in your own dashboard.

Global Coverage

150+ countries, 500+ services

Virtual numbers for Google, WhatsApp, Telegram, and hundreds more services with real-time stock availability per country and operator.

Delivery Insights

Country-level success rates

Query success-rate data per service and country to route users to the most reliable numbers and display performance metrics in your UI.

Operator-Level Routing

Target specific carriers

Pin orders to a specific mobile operator when strict routing is required, or let 1001SMS select the highest-availability carrier automatically.

One integration, full control. Redundant number pools, instant refunds, live pricing, real-time availability, and detailed account statistics — all through a single API key with scoped permissions. Focus on your product while 1001SMS handles telecom routing and number management.

Authentication

All endpoints require an API key passed in the Authorization header as a Bearer token.

Authorization: Bearer YOUR_API_KEY

Rate Limit

60 req / min

Per account, sliding window

Key Expiry

Optional

Set an expiry date in dashboard

Get your Key

User Dashboard

Generate your key from your account

Key Permissions

Permission	Grants access to
`activate`	All activation endpoints — buy, check, cancel orders
`read`	Account & lookup endpoints only (no ordering)

Example Request

curl "https://www.1001sms.com/api/v1/informative/countries" \
  -H "Authorization: Bearer YOUR_API_KEY"

Quick Start

The typical flow to receive an SMS verification code.

Buy a number

Call POST /activations/order with country, service, and provider. You get back a phone number and an order ID.

Poll for the SMS

Call POST /activations/check every 5–10 seconds with the order ID. Keep polling until hasMessage is true or status is EXPIRED.

Read the code

The check response includes messages[], each with a code field containing the extracted OTP.

Complete Example (Python)

import requests, time

API_KEY = "YOUR_API_KEY"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
BASE = "https://www.1001sms.com/api/v1"

# Step 1 — Buy a number
order = requests.post(f"{BASE}/activations/order", headers=HEADERS, json={
    "country": "US",
    "service": "google",
    "provider": "EXTRA",
    "purchaseType": "activation"
}).json()["data"]
print(f"Phone: {order['phoneNumber']}  Order: {order['id']}")

# Step 2 — Poll for SMS (up to 5 min)
for _ in range(60):
    time.sleep(5)
    check = requests.post(f"{BASE}/activations/check", headers=HEADERS,
                          json={"orderId": order["id"]}).json()["data"]
    if check["hasMessage"]:
        code = check["messages"][0]["code"]
        print(f"Code: {code}")
        break
    if check["status"] == "EXPIRED":
        print("Order expired — refund issued automatically")
        break

Errors & Status Codes

All responses use the same envelope. success: false always comes with an error string.

// Success
{ "success": true, "data": { ... } }

// Error
{ "success": false, "error": "Insufficient balance" }

HTTP Status Codes

Code	Meaning
200	OK — request succeeded
201	Created — new order placed
400	Bad Request — missing or invalid parameter
401	Unauthorized — missing, invalid, or expired API key
402	Payment Required — insufficient balance
403	Forbidden — API key lacks the required permission
404	Not Found — order, country, or service does not exist
429	Too Many Requests — rate limit exceeded (60 req/min)
500	Internal Server Error — contact support
503	Service Unavailable — provider integration is disabled

Order Status Values

Status	Description
`RENTED`	Number purchased, waiting for SMS to arrive
`COMPLETED`	SMS received, order complete
`PENDING`	Order processing
`EXPIRED`	Order timed out — automatic refund issued if no SMS was received
`REFUNDED`	Order cancelled or refunded
`BLOCKED`	Number blocked by provider — no refund

Providers

Provider ID	Description
`EXTRA`	Wide global coverage, competitive pricing
`MAIN`	High success rates, strong US/EU coverage
`EXTRA 2`	Alternative pool, useful as fallback

Number Ordering

Buy a virtual number, poll for the SMS, cancel if needed. All endpoints require the activate permission.

POST/api/v1/activations/order

Purchase a virtual phone number for SMS verification. Balance is deducted immediately. On provider failure, balance is refunded automatically. If one provider has no stock for a given country/service, try another.

Note: Numbers expire after 15–20 minutes depending on provider. Cancel within the window to receive a full refund if no SMS arrives. Some providers require a 1–2 minute wait before cancellation.

Request Body (JSON)

Name	Type	Required	Description
`country`	string	Yes	ISO country code (e.g. "US"), country slug, or 5sim country name
`service`	string	Yes	Service slug from GET /informative/services (e.g. "google", "whatsapp")
`provider`	string	Yes	Provider: EXTRA · MAIN · EXTRA 2
`purchaseType`	string	Yes	Must be "activation"
`operator`	string	No	Carrier operator name from GET /informative/operators. Defaults to "any"

Example

curl -X POST "https://www.1001sms.com/api/v1/activations/order" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"country":"US","service":"google","provider":"EXTRA","purchaseType":"activation"}'

Response

{
  "success": true,
  "data": {
    "id": "clxxx123",
    "phoneNumber": "+14155552671",
    "countryCode": "US",
    "countryName": "United States",
    "serviceId": "google",
    "serviceName": "Google",
    "operatorName": "virtual9",
    "price": 0.5,
    "status": "RENTED",
    "provider": "EXTRA",
    "providerId": "987654321",
    "purchaseType": "activation",
    "expiresAt": "2024-01-01T12:15:00.000Z",
    "rentedAt": "2024-01-01T12:00:00.000Z"
  }
}

GET/api/v1/activations/:orderId

Retrieve full details of a single order including all received SMS messages. Use this to restore order state after a restart or to display order history.

Query Parameters

Name	Type	Required	Description
`orderId`	string (path)	Yes	The order ID returned when the number was purchased

Example

curl "https://www.1001sms.com/api/v1/activations/clxxx123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "id": "clxxx123",
    "phoneNumber": "+14155552671",
    "countryCode": "US",
    "countryName": "United States",
    "serviceId": "google",
    "serviceName": "Google",
    "operatorName": "virtual9",
    "price": 0.5,
    "status": "RENTED",
    "provider": "EXTRA",
    "providerId": "987654321",
    "purchaseType": "activation",
    "expiresAt": "2024-01-01T12:15:00.000Z",
    "rentedAt": "2024-01-01T12:00:00.000Z",
    "messages": []
  }
}

POST/api/v1/activations/check

Poll the current status of an order and fetch any received SMS messages. Also triggers automatic refund if the order has expired with no SMS. Poll every 5–10 seconds — do not poll faster than every 3 seconds.

Note: Stop polling when hasMessage is true or status is EXPIRED. If the order expires with no SMS, a full refund is issued automatically on the next check call.

Request Body (JSON)

Name	Type	Required	Description
`orderId`	string	Yes	The order ID to check

Example

curl -X POST "https://www.1001sms.com/api/v1/activations/check" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orderId":"clxxx123"}'

Response

{
  "success": true,
  "data": {
    "hasMessage": true,
    "messages": [
      {
        "id": "msg1",
        "sender": "Google",
        "message": "Your Google verification code is 482910",
        "code": "482910",
        "receivedAt": "2024-01-01T12:03:00.000Z"
      }
    ],
    "status": "RENTED",
    "providerStatus": "RECEIVED"
  }
}

GET/api/v1/activations/active

List all currently active orders (status: RENTED, COMPLETED, PENDING). Paginated. Use this to resume polling after a restart.

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number. Default: 1
`limit`	integer	No	Results per page. Max: 100. Default: 20

Example

curl "https://www.1001sms.com/api/v1/activations/active?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "clxxx1",
        "phoneNumber": "+14155552671",
        "serviceId": "google",
        "status": "RENTED",
        "expiresAt": "2024-01-01T12:15:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

GET/api/v1/activations/history

Paginated history of all orders. Optionally filter by status and/or date range.

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number. Default: 1
`limit`	integer	No	Results per page. Max: 100. Default: 20
`status`	string	No	Filter by status: RENTED · COMPLETED · PENDING · EXPIRED · BLOCKED · REFUNDED
`from`	ISO 8601	No	Start date filter (e.g. 2024-01-01T00:00:00Z)
`to`	ISO 8601	No	End date filter (e.g. 2024-12-31T23:59:59Z)

Example

curl "https://www.1001sms.com/api/v1/activations/history?status=EXPIRED&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "clxxx2",
        "phoneNumber": "+14155559999",
        "serviceId": "whatsapp",
        "status": "EXPIRED",
        "rentedAt": "2024-01-01T10:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

POST/api/v1/activations/cancel

Cancel an active order. Full balance refund is issued if no SMS was received. No refund is given if a code was already delivered.

Note: MAIN and SMS-HERO providers require a 1–2 minute wait after purchase before a cancellation is allowed. The API returns a descriptive error if you attempt too early.

Request Body (JSON)

Name	Type	Required	Description
`orderId`	string	Yes	The order ID to cancel

Example

curl -X POST "https://www.1001sms.com/api/v1/activations/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"orderId":"clxxx123"}'

Response

{
  "success": true,
  "data": {
    "id": "clxxx123",
    "status": "REFUNDED",
    "refundAmount": 0.5,
    "refundReason": "Full refund - No SMS received"
  }
}

POST/api/v1/activations/cancel-all

Cancel all active orders at once. Orders that cannot be cancelled (e.g. too early or unsupported provider) are skipped and reported in the results array.

Example

curl -X POST "https://www.1001sms.com/api/v1/activations/cancel-all" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "cancelled": 3,
    "failed": 1,
    "results": [
      {
        "orderId": "clxxx1",
        "status": "REFUNDED",
        "refundAmount": 0.5
      },
      {
        "orderId": "clxxx2",
        "status": "failed",
        "refundAmount": 0,
        "error": "This operator requires a short waiting period 1-2 minutes before you can cancel an order"
      }
    ]
  }
}

GET/api/v1/activations/archive-all

Retrieve all completed, expired, or blocked orders. Read-only — does not change any order state. Useful for reconciliation and displaying completed order history.

Example

curl "https://www.1001sms.com/api/v1/activations/archive-all" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "archived": 12,
    "orders": [
      {
        "id": "clxxx3",
        "status": "EXPIRED",
        "serviceId": "google",
        "country": "US",
        "price": 0.5,
        "rentedAt": "2024-01-01T10:00:00.000Z"
      }
    ]
  }
}

Lookup

Read-only endpoints for fetching countries, services, and pricing data. No balance is deducted. Require a valid API key (no specific permission needed).

GET/api/v1/informative/countries

Returns all active countries where virtual numbers are available.

Example

curl "https://www.1001sms.com/api/v1/informative/countries" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": "clxxx",
      "name": "United States",
      "code": "US",
      "slug": "united-states",
      "flag": "🇺🇸",
      "continent": "NORTH_AMERICA",
      "phoneCode": "+1"
    },
    {
      "id": "clyyy",
      "name": "United Kingdom",
      "code": "GB",
      "slug": "united-kingdom",
      "flag": "🇬🇧",
      "continent": "EUROPE",
      "phoneCode": "+44"
    }
  ]
}

GET/api/v1/informative/services

Returns all active services (apps/platforms) available for verification. Use the slug field as the service value when ordering a number.

Example

curl "https://www.1001sms.com/api/v1/informative/services" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "id": "clxxx",
      "name": "Google",
      "slug": "google",
      "price": "0.50",
      "popular": true,
      "iconPath": "/icons/google.svg"
    },
    {
      "id": "clyyy",
      "name": "WhatsApp",
      "slug": "whatsapp",
      "price": "0.40",
      "popular": true,
      "iconPath": "/icons/whatsapp.svg"
    }
  ]
}

GET/api/v1/informative/pricing

Full pricing table across all providers. Optionally filter by country and/or service. Use this to compare operator prices before ordering.

Query Parameters

Name	Type	Required	Description
`country`	string	No	Filter by country (e.g. usa, england). Matches the country field in the pricing table.
`service`	string	No	Filter by product/service slug (e.g. google, facebook)

Example

curl "https://www.1001sms.com/api/v1/informative/pricing?country=usa&service=google" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": [
    {
      "country": "usa",
      "operator": "virtual9",
      "product": "google",
      "costPrice": 0.2,
      "resalePrice": 0.5,
      "count": 320,
      "margin": 2
    },
    {
      "country": "usa",
      "operator": "virtual4",
      "product": "google",
      "costPrice": 0.25,
      "resalePrice": 0.55,
      "count": 150,
      "margin": 2
    }
  ]
}

GET/api/v1/informative/price

Get the exact resale price for a specific country + service combination. Use this to check the price before placing an order.

Query Parameters

Name	Type	Required	Description
`country`	string	Yes	Country name or code (e.g. usa, US)
`service`	string	Yes	Service slug (e.g. google, whatsapp)

Example

curl "https://www.1001sms.com/api/v1/informative/price?country=usa&service=google" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "country": "usa",
    "service": "google",
    "price": 0.5
  }
}

GET/api/v1/informative/availability

Returns the total count of available virtual numbers across all providers for a given country + service. Use this to check stock before ordering.

Query Parameters

Name	Type	Required	Description
`country`	string	Yes	ISO country code or country name (e.g. US, United States)
`service`	string	Yes	Service slug (e.g. google, telegram)

Example

curl "https://www.1001sms.com/api/v1/informative/availability?country=US&service=google" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": 1420
}

GET/api/v1/informative/operators

Returns operator-level pricing, availability, and success rates for a given country + service. Use the operator key names from this response as the operator field when placing an order.

Query Parameters

Name	Type	Required	Description
`country`	string	Yes	ISO country code or country name
`service`	string	Yes	Service slug

Example

curl "https://www.1001sms.com/api/v1/informative/operators?country=US&service=google" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "virtual9": {
      "cost": 0.2,
      "count": 320,
      "rate": 95
    },
    "virtual4": {
      "cost": 0.25,
      "count": 150,
      "rate": 90
    },
    "any": {
      "cost": 0.2,
      "count": 470,
      "rate": 95
    }
  }
}

GET/api/v1/informative/success-rates

Returns SMS delivery success rates by country for a specific service. Higher is better. Only available for MAIN-backed data.

Query Parameters

Name	Type	Required	Description
`service`	string	Yes	Service slug (e.g. google, instagram)

Example

curl "https://www.1001sms.com/api/v1/informative/success-rates?service=google" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "google": {
      "US": 92,
      "GB": 88,
      "DE": 85
    }
  }
}

Account

Profile info, balance, transactions, and usage stats. All GET — no modifications.

GET/api/v1/informative/balance

Returns your current account balance, username, and email. Quick balance check without full profile data.

Example

curl "https://www.1001sms.com/api/v1/informative/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "balance": 12.5,
    "username": "john_doe",
    "email": "john@example.com"
  }
}

GET/api/v1/account/profile

Returns full profile info including balance, registration date, and last login timestamp.

Example

curl "https://www.1001sms.com/api/v1/account/profile" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "id": "clxxx",
    "username": "john_doe",
    "email": "john@example.com",
    "balance": 12.5,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "lastLoginAt": "2024-06-01T10:00:00.000Z"
  }
}

GET/api/v1/account/transactions

Paginated list of all transactions on your account. Filter by type and/or status.

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number. Default: 1
`limit`	integer	No	Results per page. Max: 100. Default: 20
`type`	string	No	DEPOSIT · SMS_PURCHASE · NUMBER_RENTAL · REFUND · WITHDRAWAL
`status`	string	No	PENDING · COMPLETED · FAILED · CANCELLED

Example

curl "https://www.1001sms.com/api/v1/account/transactions?type=DEPOSIT&page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "transactions": [
      {
        "id": "tx1",
        "amount": "10.00",
        "type": "DEPOSIT",
        "status": "COMPLETED",
        "description": null,
        "reference": null,
        "createdAt": "2024-01-01T00:00:00.000Z"
      },
      {
        "id": "tx2",
        "amount": "-0.50",
        "type": "SMS_PURCHASE",
        "status": "COMPLETED",
        "description": "SMS purchase for google (US)",
        "reference": "EXTRA-987654321",
        "createdAt": "2024-01-01T12:00:00.000Z"
      }
    ],
    "total": 2,
    "page": 1,
    "limit": 20
  }
}

GET/api/v1/account/stats

Aggregated account statistics: total orders placed, successful deliveries, success rate, total spent, total deposited, and transaction count.

Example

curl "https://www.1001sms.com/api/v1/account/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "totalOrders": 48,
    "totalSpent": 23.5,
    "successfulOrders": 42,
    "successRate": 87.5,
    "totalTransactions": 60,
    "totalDeposited": 50
  }
}