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

# Telephony

# Telephony

Manage phone numbers and assignments. **Full parity with the dashboard:** list, search, purchase, import (BYOC), assign, unassign, and release (delete) numbers; get agent numbers and webhook URL; list credentials.

## List Numbers

<Endpoint method="GET" path="/api/public/v1/telephony/numbers" />

**Query:** `limit` (default 50, max 100), `offset` (default 0). Returns all phone numbers for your organization (Truedy-managed and BYOC).

## Search Numbers

<Endpoint method="POST" path="/api/public/v1/telephony/numbers/search" />

**Body:** `country_code` (default `"US"`), `locality` (city/region), `area_code` (e.g. `212`), `administrative_area` (state/province), `phone_number_type` (e.g. `local`, `toll_free`, `mobile`, `national`), `api_key` (optional Telnyx key), `page` (default 1), `page_size` (default 20, max 100). Response includes `data` (array of available numbers with `phone_number`, `range`, `region_information`, `features`, `cost_information`) and `pagination` (page, page\_size, total\_results, total\_pages, has\_more).

## Purchase Number

<Endpoint method="POST" path="/api/public/v1/telephony/numbers/purchase" />

**Body:** `phone_number` (required, E.164), `api_key` (optional). Purchases a Truedy-managed number. May return **422** if the provider is not configured or the number is unavailable.

## Import Number

<Endpoint method="POST" path="/api/public/v1/telephony/numbers/import" />

**Body:** `phone_number` (required, E.164), `provider_type` (required: `telnyx`, `twilio`, or `custom_sip`). For Telnyx/Twilio include `api_key`. For `custom_sip` include `sip_username`, `sip_password`, `sip_server`. Optional: `friendly_name`, `account_sid`, `auth_token`. Returns **422** if provider is not configured or required fields are missing.

## Assign Number

<Endpoint method="POST" path="/api/public/v1/telephony/numbers/assign" />

**Body:** `number_id` (UUID), `agent_id` (UUID), `assignment_type` (`"inbound"` or `"outbound"`). Required for outbound calls: assign at least one number to the agent for outbound before creating outbound calls.

## Unassign Number

<Endpoint method="POST" path="/api/public/v1/telephony/numbers/unassign" />

**Body:** `number_id` (UUID), `assignment_type` (`"inbound"` or `"outbound"`).

## Delete (Release) Number

<Endpoint method="DELETE" path="/api/public/v1/telephony/numbers/{number_id}" />

Releases a phone number. Truedy-managed numbers are released from the provider; BYOC numbers are removed from your organization only. **Path:** `number_id` — UUID of the number (from list or assign).

## Get Agent Numbers

<Endpoint method="GET" path="/api/public/v1/telephony/agents/{agent_id}/numbers" />

Returns inbound and outbound numbers assigned to the agent. **Path:** `agent_id` — agent UUID.

## Get Webhook URL

<Endpoint method="GET" path="/api/public/v1/telephony/agents/{agent_id}/webhook-url" />

Returns the agent webhook URL for BYOC (Bring Your Own Carrier) setup. **Path:** `agent_id` — agent UUID.

## List Credentials

<Endpoint method="GET" path="/api/public/v1/telephony/credentials" />

Lists telephony credentials for your organization (BYOC providers).

**Note:** Purchase and import may return **422** when the telephony provider (Telnyx/Twilio) is not configured for your organization. Assign/unassign require valid `number_id` and `assignment_type`.