1001SMS > API Documentation

Global SMS Verification API

Integrate virtual numbers and SMS verification into your app. Order numbers by country and service, poll for received codes, and manage balance and orders via REST. Every live endpoint under https://www.1001sms.com/api/v1 is documented here with request and response examples.

API Access

1) Sign in to your account. 2) Open user menu → API. 3) Click Generate API key and copy it once.

Create API Key

Base URL

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

Auth

Authorization: Bearer YOUR_API_KEY

Spec

OpenAPI JSON

Good starting point

Everything you need to start using the platform quickly and efficiently.

Getting Started

Overview, base URL, auth, and where to start.

Authentication

Bearer key, query key fallback, permissions.

Lookup Guides

How countries, services, and pricing connect.

API Reference

All endpoints with exact request and response.

Errors & Status

Response envelope, HTTP codes, and order statuses.

Authentication

Every endpoint requires an API key. Bearer header is recommended, query key is supported for simple tests.

Authorization: Bearer YOUR_API_KEY

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

# Query key (supported)
curl "https://www.1001sms.com/api/v1/informative/countries?apiKey=YOUR_API_KEY"

Permission	Effect
`activate`	Required for all /activations/* endpoints.
`read`	Lookup + account endpoints. No ordering actions.

Simple guides using our API

Use these pricing modes to select the correct provider and operator before ordering.

Pricing guides

All examples include query API key format.

1) Prices by country

Use only country to get services/operators for one country.

https://www.1001sms.com/api/v1/informative/pricing?country=united-states&apiKey=YOUR-API-KEY

2) Prices by service

Use only service to compare countries/operators for one service.

https://www.1001sms.com/api/v1/informative/pricing?service=google&apiKey=YOUR-API-KEY

3) Prices by service and country

Use both country and service for the exact market pair.

https://www.1001sms.com:3000/v1/informative/pricing?country=united-states&service=google&apiKey=YOUR-API-KEY

Lookup Endpoints

GET/api/v1/informative/services

Available Services. Returns active services only. Use each item's slug as service in ordering and pricing requests.

Example

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

Response

{
  "success": true,
  "data": [
    {
      "id": "clx_service",
      "name": "Google",
      "slug": "google",
      "price": "0.50",
      "popular": true,
      "iconPath": "https://www.1001sms.com/icons/google.svg"
    }
  ]
}

GET/api/v1/informative/countries

Available Countries. Returns active countries only. Use country code or slug in pricing/order calls.

Example

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

Response

{
  "success": true,
  "data": [
    {
      "id": "clx_country",
      "name": "United States",
      "code": "US",
      "slug": "united-states",
      "flag": "US",
      "continent": "NORTH_AMERICA",
      "phoneCode": "+1"
    }
  ]
}

GET/api/v1/informative/pricing

Prices by country. Pass country only to get all services and operators available in that country.

Query Parameters

Name	Type	Required	Description
`country`	string	Yes	Country code, name, or slug. Example: US, Canada, canada.

Example

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

Response

{
  "success": true,
  "data": {
    "country": "Canada",
    "countryCode": "CA",
    "countrySlug": "canada",
    "services": [
      {
        "service": "google",
        "serviceName": "Google",
        "operators": [
          {
            "operator": "Foxtrot",
            "price": 0.49,
            "count": 13607,
            "deliverability": 73,
            "provider": "MAIN"
          }
        ]
      }
    ]
  }
}

GET/api/v1/informative/pricing

Prices by service. Pass service only to get all countries and operators for that service.

Query Parameters

Name	Type	Required	Description
`service`	string	Yes	Service slug from /informative/services. Example: google.

Example

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

Response

{
  "success": true,
  "data": {
    "service": "google",
    "countries": [
      {
        "country": "United States",
        "countryCode": "US",
        "countrySlug": "united-states",
        "operators": [
          {
            "operator": "virtual9",
            "price": 0.45,
            "count": 1200,
            "deliverability": 92,
            "provider": "EXTRA"
          }
        ]
      }
    ]
  }
}

GET/api/v1/informative/pricing

Prices by service and country. Pass both params to get the exact operator list for one market pair.

Query Parameters

Name	Type	Required	Description
`country`	string	Yes	Country code, name, or slug. Example: US, Canada, canada.
`service`	string	Yes	Service slug from /informative/services. Example: google.

Example

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

Response

{
  "success": true,
  "data": {
    "country": "US",
    "service": "google",
    "operators": [
      {
        "operator": "Foxtrot",
        "price": 0.49,
        "count": 13607,
        "deliverability": 73,
        "provider": "MAIN"
      }
    ]
  }
}

Activation Endpoints

POST/api/v1/activations/order

Places a new activation order and returns rented number details.

Request Body (JSON)

Name	Type	Required	Description
`country`	string	Yes	Country code, name, or slug.
`service`	string	Yes	Service slug.
`provider`	string	Yes	EXTRA, MAIN, or EXTRA 2.
`purchaseType`	string	Yes	Must be exactly "activation".
`operator`	string	No	Optional preferred operator/pool. If omitted, best option is selected.

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": "ord_123",
    "phoneNumber": "+14155552671",
    "countryCode": "US",
    "countryName": "United States",
    "serviceId": "google",
    "serviceName": "Google",
    "operatorName": "virtual9",
    "price": 0.5,
    "status": "RENTED",
    "provider": "EXTRA",
    "providerId": "987654321",
    "expiresAt": "2026-02-01T12:15:00.000Z",
    "rentedAt": "2026-02-01T12:00:00.000Z"
  }
}

POST/api/v1/activations/check

Checks provider status, stores new SMS messages, and returns current state.

Request Body (JSON)

Name	Type	Required	Description
`orderId`	string	Yes	Order id from /activations/order.

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":"ord_123"}'

Response

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

GET/api/v1/activations/{orderId}

Returns full order details with all persisted messages.

Important: Provider is returned as reseller-safe alias: EXTRA, MAIN, or EXTRA 2.

Query Parameters

Name	Type	Required	Description
`orderId`	path string	Yes	The order id in URL path.

Example

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

Response

{
  "success": true,
  "data": {
    "id": "ord_123",
    "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": "2026-02-01T12:15:00.000Z",
    "rentedAt": "2026-02-01T12:00:00.000Z",
    "messages": []
  }
}

GET/api/v1/activations/active

Returns paginated active-like orders with status in RENTED, ACTIVE, or PENDING.

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number, default 1.
`limit`	integer	No	Per page, default 20, max 100.

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": "ord_123",
        "phoneNumber": "+14155552671",
        "countryCode": "US",
        "countryName": "United States",
        "serviceId": "google",
        "serviceName": "Google",
        "operatorName": "virtual9",
        "price": 0.5,
        "status": "RENTED",
        "provider": "EXTRA",
        "providerId": "987654321",
        "rentedAt": "2026-02-01T12:00:00.000Z",
        "expiresAt": "2026-02-01T12:15:00.000Z",
        "latestMessage": null
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

GET/api/v1/activations/history

Returns paginated order history with optional status/date filters.

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number, default 1.
`limit`	integer	No	Per page, default 20, max 100.
`status`	string	No	RENTED, COMPLETED, PENDING, EXPIRED, BLOCKED, REFUNDED.
`from`	ISO date string	No	Start rentedAt date.
`to`	ISO date string	No	End rentedAt date.

Example

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

Response

{
  "success": true,
  "data": {
    "orders": [
      {
        "id": "ord_122",
        "phoneNumber": "+14155550000",
        "countryCode": "US",
        "countryName": "United States",
        "serviceId": "google",
        "serviceName": "Google",
        "operatorName": "virtual9",
        "price": 0.5,
        "status": "EXPIRED",
        "provider": "EXTRA",
        "providerId": "abc123",
        "rentedAt": "2026-02-01T09:00:00.000Z",
        "expiresAt": "2026-02-01T09:15:00.000Z",
        "messageCount": 0
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

POST/api/v1/activations/cancel

Cancels one order. Full refund is only for orders without real SMS messages.

Important: Some providers reject very early cancel attempts for about 1-2 minutes.

Request Body (JSON)

Name	Type	Required	Description
`orderId`	string	Yes	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":"ord_123"}'

Response

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

POST/api/v1/activations/cancel-all

Attempts to cancel every order with status RENTED, ACTIVE, or PENDING.

Example

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

Response

{
  "success": true,
  "data": {
    "cancelled": 2,
    "failed": 1,
    "results": [
      {
        "orderId": "ord_1",
        "status": "REFUNDED",
        "refundAmount": 0.5
      },
      {
        "orderId": "ord_2",
        "status": "failed",
        "refundAmount": 0,
        "error": "Cancel failed. Please try again later."
      }
    ]
  }
}

GET/api/v1/activations/archive-all

Lists terminal orders: EXPIRED, REFUNDED, and BLOCKED.

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": "ord_done_1",
        "status": "EXPIRED",
        "serviceId": "google",
        "country": "US",
        "price": 0.5,
        "rentedAt": "2026-02-01T08:00:00.000Z"
      }
    ]
  }
}

Account Endpoints

GET/api/v1/informative/balance

Quick account balance endpoint.

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 main account profile fields.

Example

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

Response

{
  "success": true,
  "data": {
    "id": "usr_1",
    "username": "john_doe",
    "email": "john@example.com",
    "balance": 12.5,
    "createdAt": "2025-01-01T00:00:00.000Z",
    "lastLoginAt": "2026-01-20T00:00:00.000Z"
  }
}

GET/api/v1/account/transactions

Returns paginated transactions with optional type/status filters.

Query Parameters

Name	Type	Required	Description
`page`	integer	No	Page number, default 1.
`limit`	integer	No	Per page, default 20, max 100.
`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": "2026-02-01T00:00:00.000Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

GET/api/v1/account/transactions/{id}

Returns one transaction by id.

Query Parameters

Name	Type	Required	Description
`id`	path string	Yes	Transaction id in URL path.

Example

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

Response

{
  "success": true,
  "data": {
    "id": "tx1",
    "amount": "-0.50",
    "type": "SMS_PURCHASE",
    "status": "COMPLETED",
    "description": "SMS purchase for google (US)",
    "reference": "EXTRA-12345",
    "createdAt": "2026-02-01T12:00:00.000Z"
  }
}

GET/api/v1/account/stats

Aggregated usage stats across orders and transactions.

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
  }
}

Errors and Status Codes

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

// error
{ "success": false, "error": "Error message" }

HTTP	Meaning
200	OK
201	Created
400	Invalid parameter or body
401	Missing/invalid/expired API key
402	Insufficient balance
403	Permission denied or ownership check failed
404	Entity not found
429	Rate limit exceeded
500	Internal error
503	Provider temporarily unavailable

Order Status	Used by
`RENTED`	Order currently rented and waiting for SMS.
`ACTIVE`	Appears in active endpoints as active-like state.
`PENDING`	Provider/order processing.
`COMPLETED`	Common historical state after successful flow.
`EXPIRED`	Timeout or expired session.
`REFUNDED`	Order cancelled/refunded.
`BLOCKED`	Order blocked by provider/system.

Need help?

Have a question, need some help or advice? Reach out to our support team. We're here to help!

Contact Support