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

# phones

> Numbers and outbound SMS for a persona — client.phones.

Numbers hang off an identity. Five methods. API detail: [Email & SMS](https://vetta.sh/docs/api/messaging.md).

## provision

```ts theme={"system"}
client.phones.provision(identityId: string, body: PhoneProvision): Promise<PhoneNumber>
```

`POST /v1/identities/{id}/phones`. Answers `202`, not `201`: the number exists and can receive immediately, but outbound waits on a carrier registration decision.

**tier** `"sole_prop" | "standard"` *required*

The carrier registration tier.

**legal\_name** `string` *required*

The registered legal name.

**country** `string`

ISO country; defaults server-side.

**tax\_id** `string`

`standard` only. Write-through: handed to the carrier and never stored.

**contact\_phone** `string`

`sole_prop` only — the handset that receives the verification passcode. Never stored.

**e164** `string`

Request a specific number.

**owning\_agent\_id** `string`

The agent inbound texts wake. Checked before the purchase; `null` if the agent was deleted mid-purchase.

## list

```ts theme={"system"}
client.phones.list(identityId: string, query?: { limit?: number }): Promise<Page<PhoneNumber>>
```

`GET /v1/identities/{id}/phones` — including each number's campaign/compliance status.

## update

```ts theme={"system"}
client.phones.update(identityId: string, phoneId: string, body: { owning_agent_id: string | null }): Promise<PhoneNumber>
```

`PATCH /v1/identities/{id}/phones/{phone_id}`. Sets the agent inbound texts wake, or clears it with `null`. Each text that passes the [guards](https://vetta.sh/docs/identity/inbound.md#safety-inbound-is-untrusted) then starts a session for that agent, as this persona, billed to your credits; earlier texts are not woken.

* The agent must hold the persona, or the call fails `validation_failed`.
* A deleted agent fails `not_found`.
* The woken agent can't reply by text: no agent tool sends SMS.

## release

```ts theme={"system"}
client.phones.release(identityId: string, phoneId: string): Promise<Deleted>
```

`DELETE /v1/identities/{id}/phones/{phone_id}`. **Irreversible at the carrier** — the number returns to the pool and cannot be reclaimed.

## send

```ts theme={"system"}
client.phones.send(identityId: string, phoneId: string, body: { to: string; text: string }): Promise<SmsSendReceipt>
```

`POST /v1/identities/{id}/phones/{phone_id}/send`. Answers a `202` receipt `{ accepted, from, to, sent_at }`. Refused with `compliance_pending` until the carrier approves the campaign — that is a carrier rule, not ours.


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