PleaseSMS API · v1

API одноразовых SMS

Создайте ключ в личном кабинете и используйте только на сервере. Суммы указаны в центах США.

Base URLhttps://pleasesms.com/api/v1
cURL · request
curl -X GET "https://pleasesms.com/api/v1/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"
200 OK · response
{
  "amount_minor": 5000,
  "currency": "USD"
}
  • REST · JSONJSON requests and responses over HTTPS
  • BearerAuthorization header on every request
  • USD centsAll amounts in amount_minor
  • 60 req / minRequest limit per account
01

Quick start

Create a key in the customer dashboard. Include the Authorization: Bearer header in every request.

  1. 1Create your keyCreate a key with one click in the API section of your dashboard.
  2. 2Get an offerPick a service and country from the catalogue and request a live offer.
  3. 3Buy and receive the codeOrder with the offer and poll the order until sms_code is filled.
  1. Баланс
  2. Сервисы и страны
  3. Актуальные предложения
  4. Покупка
  5. Заказ и SMS-код
02

Number rental and eSIM

Both permissions default to off. Enable them independently in your dashboard and use the same API key. Amounts are in USD cents.

Number rental

  • GET/api/v1/products
  • GET/api/v1/rental/catalog
  • GET/api/v1/rental/options?country=TR
  • POST/api/v1/rental/quotes
  • {"country":"TR","term":"30d"}

eSIM

  • GET/api/v1/esim/catalog
  • GET/api/v1/esim/options?location=TR
  • POST/api/v1/esim/quotes
  • {"packageCode":"PACKAGE_CODE","quantity":1}

Use a country and term returned by rental options. Add service for a service-specific rental. Send days for per-day eSIM packages. Use the returned quote to purchase either product.

Orders and tracking

  • POST/api/v1/{rental|esim}/orders
  • Idempotency-Key: order-0002
  • {"quote_id":"QUOTE_UUID","max_price_minor":550}
  • GET/api/v1/{rental|esim}/orders
  • GET/api/v1/{rental|esim}/orders/{id}
  • POST/api/v1/{rental|esim}/orders/{id}/refresh
  • POST/api/v1/rental/orders/{id}/cancel

Order details contain the rental SMS inbox or the eSIM installation profile. Check can_cancel before cancelling a rental.

Баланс

GET/api/v1/balance

Available balance. 5000 cents = USD 50.00. Balances round down and quotes round up.

Request and response examples
cURL
curl -X GET "https://pleasesms.com/api/v1/balance" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
{
  "amount_minor": 5000,
  "currency": "USD"
}

Сервисы и страны

GET/api/v1/catalog?service=wa

service is optional. Use the returned service and country IDs. Catalogue stock is indicative.

Request and response examples
cURL
curl -X GET "https://pleasesms.com/api/v1/catalog?service=wa" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
{
  "services": [
    {
      "id": "wa",
      "name": "WhatsApp"
    }
  ],
  "countries": [
    {
      "id": "tr",
      "name": "Türkiye",
      "stock": 42
    }
  ]
}

Актуальные предложения

GET/api/v1/offers?service=wa&country=tr

service and country are required. Returns stock, retail price and offer expiry. Use a valid quote issued to this account.

Request and response examples
cURL
curl -X GET "https://pleasesms.com/api/v1/offers?service=wa&country=tr" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
[
  {
    "id": "00000000-0000-4000-8000-000000000001",
    "service": "wa",
    "country": "tr",
    "price": {
      "amount_minor": 550,
      "currency": "USD"
    },
    "stock": 42,
    "expires_at": "2026-11-14T10:00:30.000Z"
  }
]

Покупка

POST/api/v1/orders

quote_id and max_price_minor are required. Send an 8–100 character Idempotency-Key unique to the order. After a network failure, retry with the same key and body.

Request and response examples
cURL
curl -X POST "https://pleasesms.com/api/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: order-0001" \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"00000000-0000-4000-8000-000000000001","max_price_minor":550}'
JSON · 201 Created
{
  "id": "00000000-0000-4000-8000-000000000002",
  "service": "wa",
  "country": "tr",
  "price": {
    "amount_minor": 550,
    "currency": "USD"
  },
  "status": "waiting",
  "phone": "+00000000000",
  "sms_code": null,
  "created_at": "2026-11-14T10:00:01.000Z",
  "expires_at": "2026-11-14T10:20:01.000Z",
  "cancel_available_at": "2026-11-14T10:03:01.000Z"
}

История заказов

GET/api/v1/orders?offset=0

offset is a non-negative integer. Returns up to 50 orders.

Request and response examples
cURL
curl -X GET "https://pleasesms.com/api/v1/orders?offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
{
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000002",
      "service": "wa",
      "country": "tr",
      "price": {
        "amount_minor": 550,
        "currency": "USD"
      },
      "status": "waiting",
      "phone": "+00000000000",
      "sms_code": null,
      "created_at": "2026-11-14T10:00:01.000Z",
      "expires_at": "2026-11-14T10:20:01.000Z",
      "cancel_available_at": "2026-11-14T10:03:01.000Z"
    }
  ]
}

Заказ и SMS-код

GET/api/v1/orders/{id}

Check your own order by ID. A null sms_code indicates no code is available. API orders retain their quoted USD price. Orders without a USD record return null for price. Timestamps use ISO 8601 UTC.

Request and response examples
cURL
curl -X GET "https://pleasesms.com/api/v1/orders/00000000-0000-4000-8000-000000000002" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
{
  "id": "00000000-0000-4000-8000-000000000002",
  "service": "wa",
  "country": "tr",
  "price": {
    "amount_minor": 550,
    "currency": "USD"
  },
  "status": "waiting",
  "phone": "+00000000000",
  "sms_code": null,
  "created_at": "2026-11-14T10:00:01.000Z",
  "expires_at": "2026-11-14T10:20:01.000Z",
  "cancel_available_at": "2026-11-14T10:03:01.000Z"
}

Ручная отмена

POST/api/v1/orders/{id}/cancel

Wait until cancel_available_at. An order with a received SMS is ineligible for cancellation and refund. Check for refunded status.

Request and response examples
cURL
curl -X POST "https://pleasesms.com/api/v1/orders/00000000-0000-4000-8000-000000000002/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON · 200 OK
{
  "id": "00000000-0000-4000-8000-000000000002",
  "service": "wa",
  "country": "tr",
  "price": {
    "amount_minor": 550,
    "currency": "USD"
  },
  "status": "refunded",
  "phone": "+00000000000",
  "sms_code": null,
  "created_at": "2026-11-14T10:00:01.000Z",
  "expires_at": "2026-11-14T10:20:01.000Z",
  "cancel_available_at": "2026-11-14T10:03:01.000Z"
}
03

Order statuses

  • purchasing / waitingProcessing or waiting for SMS.
  • received / completedCode received or order completed.
  • reviewThe result is under review. Check the existing order before buying again.
  • refundedCharge refunded.

Для каждого заказа используйте новый Idempotency-Key. При повторе используйте тот же ключ. Без кода отмена возможна не раньше 180 секунд. Поставщик может установить более поздний срок. Вебхуки пока недоступны.

04

Errors and limits

Limit: 60 requests per minute per account. Purchase may return 201 for a new order, 200 for an existing or resolved order, or 202 for an order under review.

400
INVALID_SELECTION / INVALID_PURCHASE / INVALID_OFFSET / INVALID_BODY

Check parameters, JSON and request headers.

401
INVALID_API_KEY

Check the key and Bearer header.

403
PRODUCT_SCOPE_REQUIRED

Enable the product permission in your dashboard.

404
ORDER_NOT_FOUND / NOT_FOUND

Check the order ID or endpoint.

409
QUOTE_EXPIRED / PRICE_LIMIT_EXCEEDED / NO_NUMBERS

Refresh the offer and check the price cap.

409
INSUFFICIENT_BALANCE

Check your available balance.

409
IDEMPOTENCY_CONFLICT / REQUEST_IN_PROGRESS

Retry the same operation with the original body.

409
EARLY_CANCEL_DENIED / CODE_RECEIVED_NO_REFUND / REFUND_NOT_CONFIRMED

Check order status and the cancellation time.

429
RATE_LIMITED

Wait for the Retry-After interval.

503
SERVICE_UNAVAILABLE / STOCK_CHECK_UNAVAILABLE / EXCHANGE_RATE_UNAVAILABLE

Retry later. Reuse the same purchase key.

Error response
{
  "error": "QUOTE_EXPIRED"
}