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

# vetta identity phone

> Provision, list, release, and send from a persona's phone numbers.

Phone numbers belong to a [persona](/docs/cli/identity), so every command takes `--identity`. Reached as `vetta identity phone <command>` — three words, where `phone` is a sub-group rather than a positional argument.

## Commands

| Command                          | Description                        |
| -------------------------------- | ---------------------------------- |
| `vetta identity phone provision` | Purchase a number for a persona.   |
| `vetta identity phone list`      | List the persona's numbers.        |
| `vetta identity phone send`      | Send an SMS as the persona.        |
| `vetta identity phone release`   | Release a number back to the pool. |

`--identity` takes either an `idn_` id or the persona's name; the API resolves both.

## provision

```bash theme={"system"}
vetta identity phone provision --identity ava \
  --tier sole_prop --legal-name "Ava Chen" --contact-phone +15555550123 --country US
```

| Flag              | Description                                                                          |
| ----------------- | ------------------------------------------------------------------------------------ |
| `--identity`      | Persona id or name (required; also accepted positionally).                           |
| `--tier`          | `sole_prop` \| `standard` (required).                                                |
| `--legal-name`    | Registered legal name (required).                                                    |
| `--country`       | ISO country code.                                                                    |
| `--tax-id`        | Required for `--tier standard`.                                                      |
| `--contact-phone` | Required for `--tier sole_prop` — a handset that receives the verification passcode. |
| `--e164`          | Request a specific number in E.164 form.                                             |

<Warning>
  **`provision` is a purchase**, and it answers `202`, not `201`. The number exists and can **receive** immediately, but outbound messaging waits on a carrier campaign decision that is not ours to make.
</Warning>

Neither `--tax-id` nor `--contact-phone` is stored by us — both are write-through to the carrier for registration.

## list

```bash theme={"system"}
vetta identity phone list --identity ava
```

```json theme={"system"}
{ "data": [], "has_more": false, "next_cursor": null }
```

| Flag         | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `--identity` | Persona id or name (required; also accepted positionally). |
| `--limit`    | Page size.                                                 |

## send

```bash theme={"system"}
vetta identity phone send --identity ava --phone pn_... --to +15555550199 --text "Your refund is processed."
```

| Flag         | Description                                         |
| ------------ | --------------------------------------------------- |
| `--identity` | Persona id or name (required).                      |
| `--phone`    | The number to send from (required).                 |
| `--to`       | Destination in E.164 form (required).               |
| `--text`     | Message body. `--message` is accepted as a synonym. |

### Outbound SMS is refused until the campaign is approved

Until the carrier approves the messaging campaign registered by `provision`, `send` is refused with `compliance_pending`. This is a **carrier rule, not a platform bug**, and the CLI reports it rather than retrying around it. Inbound continues to work throughout.

There is no way to shorten the wait from here. Check the number's campaign state with `vetta identity phone list` before scripting anything that depends on outbound delivery.

## release

```bash theme={"system"}
vetta identity phone release --identity ava --phone pn_...
```

| Flag         | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| `--identity` | Persona id or name (required).                              |
| `--phone`    | Number id. Also accepted as the second positional argument. |

<Warning>
  `release` stops the monthly charge and returns the number to the carrier's pool. It is **not recoverable** — re-provisioning will almost certainly give you a different number, and any campaign registration is lost with it.
</Warning>