FAQ: porting and numbers
Support-grade answers to the questions that come up on every port. Each answer is two or three sentences and links into the authoritative guide — read the linked section before re-typing the advice into a ticket.Rejection classes
What does NAME_MISMATCH mean?
The legal entity name you sent does not match the losing carrier’s Customer Service Record (CSR) — usually a guessed or abbreviated form. Pull the CSR and submit a supplement with the name copied verbatim. Mitigation walk: first-port walkthrough §5.
What does ADDRESS_MISMATCH mean?
The service address differs from the CSR — suite numbers, ZIP+4 vs ZIP, abbreviations. Supplement with the exact CSR address, quoted unmodified. Mitigation walk: first-port walkthrough §5.
What does BTN_MISMATCH mean?
On multi-line accounts, the billing telephone number (BTN) sent does not match the losing carrier’s billing record — it is a distinct field from the account number. Get the BTN from the CSR and supplement. Mitigation walk: first-port walkthrough §5.
What does a PIN rejection mean?
The transfer PIN from the losing carrier was missing or wrong — on port-in the carrier rejects it; on port-out you get401 PORT_OUT_PIN_MISMATCH. Confirm the PIN with the carrier before resubmitting. Mitigation walk: first-port walkthrough §5.
What does LOA_INVALID mean?
The Letter of Authorization is missing numbers, unsigned, a photo of a screen, over 30 days old, or below legibility. Redo it as a real PDF at >=200 dpi with every porting number listed, then cancel and resubmit. Mitigation walk: first-port walkthrough §5.
Before you submit
Where does the pre-import CSR checklist come from?
Run the six-item pre-import checklist before any API call: CSR in hand, authorized signer named, LOA scan ready, port-out PIN set on existing numbers, country rules confirmed, and the eligibility gate passed. Source: first-port walkthrough §2.How do I gate a port before submitting?
CallPOST /numbers/porting/pre-validate and gate on ready: true — it runs the portability check and lints the CSR fields in the same pass. The full gate sequence (including bulk preflight) is in Port a number end-to-end §2.
What is the difference between a draft and a submitted port?
A draft (draft: true at create) is stored locally with staging: "draft" and never reaches a carrier; a submitted port is dispatched immediately. A draft only moves once the LOA is uploaded and signed. Walkthrough: Port a number end-to-end §3.
Why should I not park a port in draft?
No carrier ever sees a draft, so no FOC date is ever issued for it and the review clock never starts. Cancel the draft and re-create it when the CSR and signer are ready. Details: Port a number end-to-end §3.During the port
When can I still cancel a port?
Cancel works while the request issubmitted or reviewing; once the losing carrier approves it, cancel returns 409 and the port completes on the carrier’s schedule. Port-out cancellation is honored only until the FOC cutover. Cancel boundaries: first-port walkthrough §1.
How do I track the FOC date?
CallGET /numbers/porting/:id/timeline — it expands the flat status into per-stage entries and echoes focDate as soon as the carrier assigns one. The dashboard’s porting wizard renders the same timeline. Tracking walkthrough: Port a number end-to-end §6.
Which webhooks should I subscribe to for porting?
Subscribe tonumber.ported, porting.request.loa_signed, porting.request.supplement_submitted, porting.request.manual_review_required, and porting.request.cancelled. Delivery is at-least-once, so dedupe on the event id. Event table: first-port walkthrough §4.
What happens when a rejection is operator_fixable vs needs_carrier vs fatal?
operator_fixable means fix your own data and supplement inside the 7-day amend window; needs_carrier means the losing carrier must resolve it; fatal (for example NUMBER_NOT_PORTABLE) means the number stays at the losing carrier. Severity model: Port a number end-to-end §6.
How does the 7-day supplement window work?
After a fixable rejection, you have 7 days to submit a supplement before the FOC clock restarts. The row sits insupplement_submitted until the carrier accepts it back into reviewing or rejects again. Walkthrough: Port a number end-to-end §5.
Protecting your numbers
How do I stop an unauthorized port-out?
Set a port-out PIN (4-32 chars) withPOST /numbers/:id/port-out-protection — any port-out attempt without the matching PIN rejects 401 before the carrier is contacted. There is no recovery path, so record the PIN in your secret store when you set it. Setup walkthrough: Port out safely §2.
What statuses block a port-out?
released, suspended, parked, and port_out_pending all reject the submit with 409, so check GET /numbers/:id first. Full pre-flight order: Port out safely §2.
When does a port-out become irreversible?
After the FOC cutover, the winning carrier owns the number — cancel no longer applies and there is no rollback. Treat the cancel window as real: a delayed decision past FOC expiry means the number is gone. Cancel discipline: Port out safely §1.Special cases
How do toll-free numbers move?
Toll-free numbers do not use the standard carrier-to-carrier port flow — they move by changing the Responsible Organization (RespOrg) viaPOST /numbers/porting/toll-free/resporg. Submitted outside the LNP flow; post-port administration runs the same way. Carve-out details: Port a number end-to-end §1.
Can I practice porting flows in the sandbox?
Yes — the sandbox’s reserved magic numbers (from the+1 555 01XX range) let you run the full port and DLR exercise loop without touching a real carrier. Provisioning shapes: Sandbox test mode and Sandbox magic numbers playbook.
How do I migrate more than a handful of numbers at once?
Use the bulk CSV flow atPOST /numbers/port-in/bulk-csv — up to 1000 rows per upload, each row becoming its own porting request you finish through the dashboard. CSV shape and caps: Port a number end-to-end §8.