POST/v1/sms/purchase

Buy a number

Buys a virtual SMS number for OTP receipt on the given service.

Required scope: sms.purchaseRate limit: 10 rps

Parameters

servicestringrequired

Service slug, e.g. "whatsapp".

country_codestringrequired

ISO-3166-1 alpha-2, lowercase.

Code samples

curl -X POST "https://samaprime.com/api/v1/sms/purchase" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"service":"example","country_code":"example"}'

Response

→ 201
{
  "data": {
    "order_id": "ord_01J8X9AABBCCDD",
    "phone_number": "+15551234567",
    "expires_at": "2026-08-10T15:02:00Z",
    "cost_usd": "0.8000",
    "cost_locked_from_balance": true
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-08-06T12:00:00Z"
  }
}

Errors

Status	Code
400	`invalid_service` No active service/country pairing matches this request.
422	`insufficient_balance` Wallet balance is lower than the number's price.
409	`unavailable` This service/country is no longer available.
409	`no_numbers` No numbers currently available for this service/country.
429	`provider_rate_limited` The upstream SMS provider is rate-limiting purchases — try again shortly.
500	`provider_error` The upstream SMS provider returned an error.