Catalog & Quotes

Discover service codes and request current quotes before creating an order.

Catalog requests are read-only. Quote requests check live inventory and pricing but do not issue invoices or reserve a number.

Receive-SMS catalog

GET /v2/receive-sms/catalog?country={country}

country accepts auto, a supported numeric country ID, ISO alpha-2 code, or country name. It defaults to auto.

curl -sS 'https://api.sms4sats.com/v2/receive-sms/catalog?country=auto'

{
  "type": "receive-sms",
  "country": "auto",
  "services": [
    { "code": "tg", "name": "Telegram" },
    { "code": "go", "name": "Google,youtube,Gmail" }
  ],
  "updatedAt": "2026-09-30T19:00:00.000Z"
}

The catalog lists supported service metadata, not guaranteed inventory. Use services[].code as service, then request a quote.

Quote a receive-SMS order

POST /v2/receive-sms/quote

Body field	Type	Required	Description
country	string	Yes	auto, numeric ID, ISO code, or country name
service	string	Yes	Catalog code or recognized service name
referral	string	No	Referral metadata, maximum 320 characters
clientRequestId	string	No	Client correlation value, maximum 200 characters

curl -sS -X POST https://api.sms4sats.com/v2/receive-sms/quote \
  -H 'Content-Type: application/json' \
  -d '{"country":"auto","service":"tg"}'

{
  "type": "receive-sms",
  "country": "151",
  "service": "tg",
  "durationMinutes": null,
  "availability": 120,
  "priceSats": 350
}

country may differ from the request when auto selects a route. Quotes may be cached for up to five minutes, and creation may reuse that short-lived quote. Provider allocation after payment is the definitive inventory check. Always use the creation response's priceSats for payment UI.

Rental catalog

GET /v2/rent-numbers/catalog?service={service}&durationMinutes={minutes}

• service defaults to full.

• durationMinutes is normalized upward to a whole hour with a minimum of 120 and a maximum request value of 43,200.

{
  "type": "rent-number",
  "service": "full",
  "durationMinutes": 120,
  "countries": [
    {
      "country": "1",
      "availability": 3,
      "durationMinutes": 120,
      "priceSats": 1800
    }
  ],
  "updatedAt": "2026-09-30T19:00:00.000Z"
}

An empty countries array means no matching rental is currently available.

Quote a rental

POST /v2/rent-numbers/quote

curl -sS -X POST https://api.sms4sats.com/v2/rent-numbers/quote \
  -H 'Content-Type: application/json' \
  -d '{"country":"1","service":"full","durationMinutes":120}'

The response has the same fields as a receive-SMS quote, with type: "rent-number" and a normalized durationMinutes.

Availability is inherently volatile. Handle 409 UNAVAILABLE even when a quote succeeded moments earlier.