> ## 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, update, release, and send from a persona's phone numbers.

Phone numbers belong to a [persona](https://vetta.sh/docs/cli/identity.md), 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 update` | Set or clear the agent a number's texts are for. |
| `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. |
| `--agent` | The agent inbound texts to this number are for (`owning_agent_id`), as an inbox names one for mail. |

> [!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.

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.

## update

```bash theme={"system"}
vetta identity phone update --identity ava --phone pho_... --agent agt_...
vetta identity phone update --identity ava --phone pho_... --none
```

| Flag | Description |
| - | - |
| `--identity` | Persona id or name (required). |
| `--phone` | Number id. Also accepted as the second positional argument. |
| `--agent` | The agent inbound texts to this number are for (`owning_agent_id`). |
| `--none` | Clear the number's agent. Pass exactly one of `--agent` and `--none`. |

Once set, each inbound text that passes the [guards](https://vetta.sh/docs/identity/inbound.md#safety-inbound-is-untrusted) starts a session for that agent, as this persona, billed to your credits. Texts that arrived before are not woken. The agent must hold the persona (`vetta identity attach`). `--none` stops wakes. The woken agent can't reply by text: no agent tool sends SMS.

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.