Create a Bearer-Token Order
Create an idempotent receive-SMS or rental order and receive its hold invoice and access token.
POST /v2/receive-sms/orders
POST /v2/rent-numbers/orders
Headers
Content-Type: application/json
Yes
JSON request body
Idempotency-Key: <UUID v4>
Yes
Random UUID v4 scoped to the selected product
X-Idempotency-Key is accepted as an equivalent header. Prefer Idempotency-Key.
Body
country
string
Required
Required
auto, numeric ID, ISO code, or country name
service
string
Required
Required
Service code or recognized name
durationMinutes
integer
Ignored/omit
Optional
1–43,200; normalized to at least 120 and a whole hour
referral
string
Optional
Optional
Maximum 320 characters
clientRequestId
string
Optional
Optional
Client correlation value, maximum 200 characters
The endpoint path determines the product type. Do not send a conflicting type field.
Example
curl -sS -X POST https://api.sms4sats.com/v2/receive-sms/orders \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: 17165eb7-d770-4a21-abd4-90295ac15252' \
-d '{"country":"US","service":"tg","clientRequestId":"checkout-123"}'Response: HTTP 201 Created
Idempotent retries
Same key + same normalized body: returns the original order and invoice.
Same key + different body:
409 IDEMPOTENCY_CONFLICT.Concurrent retry while creation is running:
409 IDEMPOTENCY_IN_PROGRESS; retry the same request and key after a short delay.Network timeout or ambiguous
5xx: retry the same request and key. Never generate a new key until you know the original request did not create an order.
accessToken is returned as a secret order capability. Persist it before navigating away. orderReference packages the order ID and token for client-side portability; it is equally sensitive.
Last updated