PleaseSMS API · v1

Single-use SMS API

Create a key in your dashboard. Use it only on your server. Amounts are in USD cents.

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. Balance
  2. Service and country catalogue
  3. Current offers
  4. Purchase
  5. Order and SMS code
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.

Balance

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

Service and country catalogue

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

Current offers

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

Purchase

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

Order history

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

Order and SMS code

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

Manual cancellation

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.

Send a new Idempotency-Key for each order. Reuse the key when retrying. With no code, cancellation opens after at least 180 seconds. A supplier may impose a later time. Webhooks are unavailable.

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