> ## 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. Four methods. API detail: [Email & SMS](/docs/api/messaging).

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

<ResponseField name="tier" type="&#x22;sole_prop&#x22; | &#x22;standard&#x22;" required>The carrier registration tier.</ResponseField>
<ResponseField name="legal_name" type="string" required>The registered legal name.</ResponseField>
<ResponseField name="country" type="string">ISO country; defaults server-side.</ResponseField>
<ResponseField name="tax_id" type="string">`standard` only. Write-through: handed to the carrier and never stored.</ResponseField>
<ResponseField name="contact_phone" type="string">`sole_prop` only — the handset that receives the verification passcode. Never stored.</ResponseField>
<ResponseField name="e164" type="string">Request a specific number.</ResponseField>

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

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