Skip to main content

SMS Port-Out

When a customer wants to send or receive text messages on a phone number hosted by DialStack using a third-party messaging provider, that provider sends a messaging transfer request (an SMS port-out) to the carrier. The carrier passes it to DialStack, which approves or denies it automatically at request time.

Authorization is per number and time-boxed. Every number starts locked — a port-out request is denied. To allow one, you open a window on that specific number: while the window is open, an incoming port-out request for it auto-approves; once the window's expiry passes (or you lock it again), requests are denied.

Opening or locking a window (admin)​

On a phone number's detail page, the SMS Port-Out card (platform-admin only) shows the number's current state:

  • Locked — port-out requests are denied.
  • Open until <date> — requests auto-approve until then.

Enter how many days the window should stay open and select Open window to authorize port-out from now until that many days out (maximum 365). Select Lock to close it again immediately. The window is fixed when you open it — it does not move if you change it later for other numbers.

Automating it (API)​

The same control is available on the public API as a singleton sub-resource on the phone number, so a platform can script it (for example, opening a window right after provisioning a number for a customer who is moving their texting):

Text
GET  /v1/phone-numbers/:phone_number_id/sms-port-out   → { "expires_at": "2026-06-29T09:30:00Z" | null }
POST /v1/phone-numbers/:phone_number_id/sms-port-out     { "expires_at": "2026-06-29T09:30:00Z" }   # open until then
POST /v1/phone-numbers/:phone_number_id/sms-port-out     { "expires_at": null }                      # lock

expires_at is the instant the window stays open until; null means locked. It must be a future timestamp no more than 365 days out. The endpoint is authorized with your API key (plus the DialStack-Account header) — it is not exposed to embedded SDK session tokens.

The SDK wraps it as client.phoneNumbers.retrieveSmsPortOut(id) and client.phoneNumbers.updateSmsPortOut(id, { expiresAt }).

On this page