PleaseSMS API · v1

API SMS à usage unique

Créez une clé dans votre espace client et utilisez-la uniquement sur votre serveur. Les montants sont en cents américains.

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. Solde
  2. Services et pays
  3. Offres actuelles
  4. Achat
  5. Commande et code 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.

Solde

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

Services et pays

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

Offres actuelles

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

Achat

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

Historique des commandes

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

Commande et code 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"
}

Annulation manuelle

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.

Utilisez une nouvelle Idempotency-Key par commande et réutilisez-la en cas de nouvelle tentative. Sans code, l’annulation est possible après au moins 180 secondes. Le fournisseur peut imposer un délai plus long. Les webhooks ne sont pas encore disponibles.

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