​

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

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

​

Search Numbers

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

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

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

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

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

​

Delete (Release) Number

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

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

​

Get Webhook URL

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

​

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