smsape API

Returns the calling account's identity and wallet balance. Use it to verify a key works and to gate purchases when the balance is too low.

curl https://smsape.com/api/v1/me \
  -H "Authorization: Bearer sk_..."

{
  "user": { "id": "cku...", "email": "[email protected]", "name": "Acme", "createdAt": "2026-05-01T09:30:00.000Z" },
  "wallet": { "balanceCents": 1250, "holdCents": 0, "balanceUsd": 12.5 }
}

Every purchasable service, sorted by popularity. Use the slug as the service identifier in buys and price lookups.

curl https://smsape.com/api/v1/catalog/services \
  -H "Authorization: Bearer sk_..."

{
  "items": [ { "slug": "facebook", "name": "Facebook", "iconUrl": "https://...", "sortOrder": 10 }, ... ],
  "total": 4000
}

Every purchasable country. Both the slug ("united-states") and the ISO code ("us") are accepted anywhere a country is expected.

curl https://smsape.com/api/v1/catalog/countries \
  -H "Authorization: Bearer sk_..."

{
  "items": [ { "slug": "united-states", "name": "United States", "code": "us", "flagUrl": "https://...", "sortOrder": 1 }, ... ],
  "total": 190
}

Live activation prices and stock for one country. priceCents is the cheapest in-stock source (best case); maxPriceCents is the priciest in-stock tier. A buy fills from cheapest to dearest, so the actual charge can rise toward maxPriceCents when the cheapest tier is sold out — send maxPrice on the buy to lock an absolute ceiling. lastUpdated tells you when this country's cache was last refreshed, so you know how long to trust a local copy.

curl "https://smsape.com/api/v1/catalog/prices?country=us&service=facebook" \
  -H "Authorization: Bearer sk_..."

{
  "country": "united-states",
  "lastUpdated": "2026-07-21T10:02:11.000Z",
  "items": [
    { "service": "facebook", "priceCents": 21, "priceUsd": 0.21,
      "maxPriceCents": 84, "maxPriceUsd": 0.84, "stockCount": 10342 }
  ],
  "total": 1
}

Buy a number. Your wallet is debited at the number's actual price. Send maxPrice (dollars) to cap it — we never charge above it, and if nothing fits the cap the buy is refused with 409 + suggestedPriceCents so you can decide to retry with a higher ceiling. Returns 201 with the number immediately; SMS arrives asynchronously (poll or webhook).

{ "country": "us", "service": "facebook", "maxPrice": 0.40 }

curl -X POST https://smsape.com/api/v1/activations \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"country":"us","service":"facebook","maxPrice":0.40}'

201 {
  "activation": {
    "id": "act_abc", "service": "facebook", "country": "united-states",
    "number": "+1206...", "status": "PENDING", "priceCents": 21,
    "createdAt": "...", "updatedAt": "...",
    "activationId": "act_abc", "phoneNumber": "+1206...",          // sms-activate-style aliases
    "activationCost": 0.21, "activationStatus": "PENDING"
  }
}
409 { "error": "...", "suggestedPriceCents": 55, "suggestedPrice": 0.55 }   // cap too low

List your activations, newest first, cursor-paginated.

curl "https://smsape.com/api/v1/activations?limit=50" \
  -H "Authorization: Bearer sk_..."

{
  "items": [ { "id": "act_abc", "service": "facebook", "country": "united-states",
               "number": "+1206...", "status": "SUCCESS", "priceCents": 21,
               "createdAt": "...", "updatedAt": "...", ...aliases } ],
  "nextCursor": "act_xyz"   // null when this is the last page
}

Current status + every SMS received so far. While the activation is PENDING this endpoint also checks for new SMS server-side (at most once per 3 seconds), so polling it in a loop is the intended usage — 2–5s intervals are ideal.

curl https://smsape.com/api/v1/activations/act_abc \
  -H "Authorization: Bearer sk_..."

{
  "activation": {
    "id": "act_abc", "service": "facebook", "country": "united-states",
    "number": "+1206...", "status": "SUCCESS", "priceCents": 21,
    "createdAt": "...", "updatedAt": "...",
    "messages": [
      { "id": "sms_1", "fromNumber": "Facebook", "text": "FB-84921 is your code", "createdAt": "..." }
    ]
  }
}

Cancel a PENDING activation and refund the wallet in full. A short hold window applies after purchase (≈2 minutes, up to 3 for some numbers) — cancelling earlier returns 425 with a Retry-After header telling you how many seconds to wait. Activations that already received an SMS can't be cancelled.

curl -X POST https://smsape.com/api/v1/activations/act_abc/cancel \
  -H "Authorization: Bearer sk_..."

{ "ok": true, "refundedCents": 21 }
425 { "error": "..." }   // + Retry-After: <seconds>

Every rentable locale with its full per-duration price table. pricing values are cents keyed by duration; cheapestPrice is the lowest tier in dollars. Locales can sell out — a listed price is not a stock guarantee.

curl https://smsape.com/api/v1/rent/catalog \
  -H "Authorization: Bearer sk_..."

{
  "items": [
    { "rentalId": "US", "name": "United States", "tag": "US", "region": "US",
      "pricing": { "halfDay": 250, "oneDay": 300, "oneWeek": 900, "oneMonth": 2200, ... },
      "cheapestPrice": 2.5 }
  ]
}

Rent a number. The wallet is debited at the catalog price for the chosen locale + duration; the number is returned immediately and stays yours until expiresAt.

{ "locale": "US", "duration": "oneWeek" }

curl -X POST https://smsape.com/api/v1/rent/orders \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"locale":"US","duration":"oneWeek"}'

201 {
  "rentOrder": { "id": "rent_xyz", "country": "US", "product": "oneWeek",
                 "number": "+1206...", "status": "PENDING", "priceCents": 900,
                 "expiresAt": "2026-07-28T12:00:00.000Z", "createdAt": "..." }
}

List your rent orders, newest first, cursor-paginated (same limit/cursor params as activations). Each row includes messageCount so you can poll cheaply and fetch details only when it grows.

curl https://smsape.com/api/v1/rent/orders \
  -H "Authorization: Bearer sk_..."

{
  "items": [ { "id": "rent_xyz", "country": "US", "product": "oneWeek", "number": "+1206...",
               "status": "PENDING", "priceCents": 900, "expiresAt": "...",
               "createdAt": "...", "updatedAt": "...", "messageCount": 3 } ],
  "nextCursor": null
}

Rent order details + full SMS history (up to 500 messages, oldest first). Fresh SMS are pulled from the carrier on each call (throttled to once per 5s per order, bounded to 2.5s so the response never stalls) — polling this endpoint is the intended way to read incoming messages.

curl https://smsape.com/api/v1/rent/orders/rent_xyz \
  -H "Authorization: Bearer sk_..."

{
  "rentOrder": {
    "id": "rent_xyz", "country": "US", "product": "oneWeek", "number": "+1206...",
    "status": "PENDING", "priceCents": 900, "expiresAt": "...", "createdAt": "...", "updatedAt": "...",
    "messages": [ { "id": "rsms_1", "fromNumber": "Telegram", "text": "Code: 84921", "receivedAt": "..." } ]
  }
}

Extend an active rental by another duration. The wallet is debited at the current catalog price for that duration and expiresAt moves forward. Cancelled rentals can't be extended.

{ "duration": "oneMonth" }

curl -X POST https://smsape.com/api/v1/rent/orders/rent_xyz/extend \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"duration":"oneMonth"}'

{
  "rentOrder": { "id": "rent_xyz", ..., "expiresAt": "2026-08-28T12:00:00.000Z" },
  "extension": { "durationAdded": "oneMonth", ... }
}

Cancel an active rental and refund its price. Not possible once the rental has expired (it was fully used) or is already cancelled. If the carrier refuses the cancel, 400 is returned and nothing is charged or changed.

curl -X POST https://smsape.com/api/v1/rent/orders/rent_xyz/cancel \
  -H "Authorization: Bearer sk_..."

{
  "rentOrder": { "id": "rent_xyz", ..., "status": "CANCELLED" },
  "refundedCents": 900
}