> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osis.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Line porting

> Bring your existing phone number onto a Comms dedicated line — access requires permission.

Bring an existing phone number onto Comms by porting it onto a **dedicated** line.

<Warning>
  **This API requires permission.** Request access before use. Having a Comms API key (and `comms_lines_write`) alone is **not** enough — the org must also be allowlisted by Osis ops (`COMMS_PORT_ALLOWED_ORG_IDS`). Unapproved orgs receive `403 permission_denied`. Live Tello automation is a separate kill switch and stays off until ops enables it.
</Warning>

## How it works

1. **Dedicated line on the account** — You lock the dedicated E.164 already assigned to your org (the number your agents use in dedicated mode).
2. **One-time port** — You submit LNP details for the number you want to bring (`target_e164`). That BYO number replaces the locked dedicated line after the port completes.
3. **Exactly one attempt** — Lock is irreversible via this API. Each locked line accepts a single port submit.

Contact your **current carrier** for port-out details (account number, porting PIN, account holder name, and service address). Port speed and success depend on an **exact match** to the losing carrier’s records.

### If you do not have a dedicated number yet

If you just signed up for a dedicated plan and want to bring your number over first:

1. Get an **unused empty dedicated** inventory line assigned to your org (never a shared platform line).
2. Lock that E.164, then submit the port so your BYO number lands on it.

Shared lines cannot be locked or ported (`shared_line_not_portable`).

## Endpoints

| Method | Path                                                               | Scope               |
| ------ | ------------------------------------------------------------------ | ------------------- |
| `POST` | [`/api/v1/comms/lines/{e164}/lock`](/messages-api/lock-line)       | `comms_lines_write` |
| `GET`  | [`/api/v1/comms/lines/{e164}/port`](/messages-api/get-line-port)   | `comms_lines_read`  |
| `POST` | [`/api/v1/comms/lines/{e164}/port`](/messages-api/start-line-port) | `comms_lines_write` |

## Status machine

```
number_locked → port_submitted → port_in_progress → port_completed
                                              ↘ port_failed
```

## Errors

| Code                                                                 | When                                                          |
| -------------------------------------------------------------------- | ------------------------------------------------------------- |
| `permission_denied`                                                  | Org is not on the Port API allowlist (or allowlist is empty). |
| `missing comms_lines_write scope` / `missing comms_lines_read scope` | API key lacks the required scope.                             |
| Other port codes (`line_not_found`, `line_already_locked`, …)        | See endpoint pages.                                           |

## Privacy

`GET` port status never returns LNP secrets (PIN, account number, address, names) or ciphertext — only status, timestamps, and safe error fields.