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

# Phone numbers and SIP

> Connect an Agent to managed, BYO, or SIP calling through the API.

Agent configuration controls behavior. Phone-number and SIP resources control how calls reach the Agent.

## Verify assigned numbers

List the selected account's assigned phone numbers with `GET /api/v2/phoneNumbers?targetAccountId=...` before and after changing telephony setup.

## Assign a Vida-managed number

1. Discover the organization's supported numbering providers.
2. Search for available numbers by locality, prefix, or phrase.
3. Present the candidates to the user.
4. Assign the user-approved number to the Agent account.
5. Read assigned numbers and place a test call.

## Assign a BYO number

Use the BYO assignment endpoint when the user already controls the number. Verify ownership and routing requirements before assignment, then confirm the number appears on the selected Agent account.

Returning or disconnecting a number stops its current routing. Require explicit user confirmation before calling that operation.

## Configure SIP registration

Use registration when the Agent should register to an external PBX or SIP provider as an extension.

1. Check address-of-record availability with the
   [availability endpoint](/docs/api-reference/sip/check-sip-registration-aor-availability).
2. Create or update the selected Agent account's
   [registration](/docs/api-reference/sip/create-or-update-sip-registration).
3. [Read the registration](/docs/api-reference/sip/get-sip-registration) and verify its status.
4. Place representative inbound and outbound calls for the intended PBX flow.

Updating a registration is different from adding a direct SIP route. Configure both only when the
intended topology requires both.

## Allow direct inbound SIP

Use the SIP IP access list when a PBX or carrier will send SIP INVITEs directly to the Agent's Vida
SIP URI.

1. [Read the current access list](/docs/api-reference/sip/list-sip-ip-whitelist).
2. Add every approved source signaling IP with the
   [IP access endpoint](/docs/api-reference/sip/add-ip-to-sip-ip-whitelist).
3. Re-read the list and send a test call from an allowed source to the Agent's SIP URI.

An omitted or incorrect source IP prevents the inbound call from reaching the Agent. These access-list
operations require developer API access.

## Route direct outbound SIP

Use an outbound route when Vida should send calls directly to a SIP domain, IP, or proxy rather than
through an Agent registration.

1. [Read the current routes](/docs/api-reference/sip/list-sip-outbound-routes).
2. Add the exact approved [outbound route](/docs/api-reference/sip/add-sip-outbound-route), including only
   the port, transport, or proxy settings required by the destination.
3. Re-read the routes and place a representative outbound call.

Outbound-route operations require developer API access. Route order and overlapping destinations can
affect call delivery, so preserve unrelated routes and verify the complete resulting list.

## Change SIP safely

Use `targetAccountId` to select the Agent account for every account-scoped SIP request. Read the
current resource before changing it and verify it afterward. Removing a registration, source IP, or
outbound route can interrupt calls; require explicit approval for the exact removal and test the
remaining call path after it completes.

The generated SIP endpoint pages define the exact current payloads, transports, and response shapes.