Skip to navigation

SMS numbers

View as Markdown

SimJuno eSIMs are data-only: they have no phone number of their own. An SMS number is a phone number you rent separately for a set number of days. SMS sent to it are kept in its inbox and, when it is linked to an eSIM, forwarded to that eSIM as an SMS. Use it to receive one-time verification codes.

An SMS number can only receive SMS. It cannot send SMS or make or receive calls.

Which eSIMs can receive forwarded SMS

A number can be linked to an eSIM you ordered whose plan has smsStatus 1 or 2 (shown on GET /esim/destination/{slug} and GET /esim/package/{slug}) and that has not expired. Plans with smsStatus 0 cannot receive SMS. You can rent a number without linking it and read its SMS through the API instead.

Flow

  1. API — Call GET /sms-number/offers to list the numbers on sale. Each offer has a product_id and the rental lengths (days) with their price. The list is empty while no numbers are on sale. Prices use the same factor of 10,000 as your balance, and the account discount_percent does not apply to SMS numbers.
  2. API — Call POST /sms-number/order with the product_id, days, a unique reseller transaction_id and, optionally, the esim_id to forward to. The price is debited from your reseller wallet and the rented number is returned straight away. To safely retry, reuse the same transaction_id with the same product_id and days. If no number can be supplied, you are not charged and must use a new transaction_id to try again.
  3. API — To link, change or remove the eSIM later, call PUT /sms-number/{id}/esim with an esim_id, or null to keep new SMS in the inbox only.
  4. Webhook/API — Wait for an SMS_RECEIVED webhook, or poll GET /sms-number/{id}/messages. Each message’s forward_status shows whether it reached the eSIM.
  5. API — Call GET /sms-number to list your numbers and GET /sms-number/{id} for one of them. A number stops receiving SMS at expires_at.

Refunds

Call POST /sms-number/{id}/refund to return the price to your reseller wallet. This is only possible before refundable_until and before the number has received any SMS. refundable_until is null for numbers that cannot be refunded.