# Number porting

Source: https://joinsimplesms.com/docs/porting
Index: https://joinsimplesms.com/llms.txt

You can bring a number you already own. Porting is a carrier-side process with
paperwork and multi-day timelines, so it runs as a tracked request rather than
an instant API call.

## What we need

- The number, your current carrier, and the account number with them
- The last 4 of your account PIN (if your carrier uses one)
- The name of the person authorized to approve the transfer

Submit from Console → Numbers → Port a number (admins only).

## Timeline

| Status | Meaning |
| --- | --- |
| `requested` | We received your request. |
| `submitted` | Filed with the carrier. |
| `foc_set` | The carrier set a Firm Order Commitment date. |
| `complete` | The number is live on SimpleSMS. |
| `rejected` | The carrier rejected it; the note says why (usually a detail mismatch). |

The status timeline is visible in the console; keep the old service active
until the port completes.

## Port many at once

Console → Numbers → Port many numbers takes a CSV: either one column of
numbers (the form supplies carrier, account number, PIN and authorized name
for all of them) or a header row with `number`, `carrier`,
`account number`, `pin`, `authorized name` columns for numbers spread
across old carriers. Every row is checked before anything is filed:

| Row status | Meaning |
| --- | --- |
| ready | Will be filed. |
| not a valid number | Not a US/Canada number. |
| duplicate | Appears earlier in the file. |
| already yours | Already on your SimpleSMS account. |
| port already open | A request for it is in flight (rejected ones can be re-filed). |
| missing details | Carrier, account number or authorized name missing. |

Only ready rows are filed. You can choose a pool and tags for the numbers to
join when their port completes. Accounts with live access can run a
portability check first: current carrier and whether the number can port,
per number.

## Moving from Twilio, Telnyx or Plivo

Console → Numbers → Import from Twilio / Telnyx / Plivo reads your account
with the credentials you paste (Twilio Account SID + Auth Token, Telnyx API
key, Plivo Auth ID + Auth Token). They are used once, for read-only requests,
and never stored. You get a plan to review:

- **Numbers to port**, each marked will port / already on SimpleSMS / port already
  open / not SMS-enabled / not US-Canada.
- **Pools to recreate** from Twilio Messaging Services, Telnyx messaging
  profiles, or Plivo Powerpacks. Numbers join them as their ports complete.
- **Webhook URLs found** (inbound and status callbacks), offered as SimpleSMS
  webhook endpoints. Your handler has to accept SimpleSMS's JSON events, not the
  old provider's callback format.

Opt-out lists aren't exposed by any of the three APIs; SimpleSMS enforces
STOP/START itself, and you can import an existing suppression list with
`POST /v1/consent/import`. Running the plan only creates SimpleSMS-side
things (port requests, pools, webhooks); nothing changes at the old provider
until each carrier port completes.