Telephony

Manage phone numbers and assignments: list, search, purchase, import (BYOC), assign, unassign, release (delete) numbers, get agent numbers and webhook URL, and list credentials. This is the documented public surface; provider reference/configuration and analytics operations remain dashboard/private capabilities.

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), features, best_effort, reservable, exclude_held_numbers, quickship, limit, api_key (optional Telnyx key), page (default 1), and page_size (default 20, max 100). All listed search filters are forwarded to the provider. Response includes data and pagination (page, page_size, total_results, total_pages, has_more).

Purchase Number

Purchase a Truedy-managed phone number through the API. The number must come from the available-number search results and must be sent in E.164 format. Authentication: Include your Truedy API key as a bearer token.

curl -X POST https://api.truedy.ai/api/public/v1/telephony/numbers/purchase \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"+14155551234"}'

const response = await fetch(
  "https://api.truedy.ai/api/public/v1/telephony/numbers/purchase",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TRUEDY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phone_number: "+14155551234" }),
  },
)

const { data } = await response.json()
console.log(data.id, data.phone_number)

Request body:

Field	Type	Required	Description
`phone_number`	string	Yes	E.164 phone number selected from the search results, for example `+14155551234`

The response contains the purchased number in data, including its id, phone_number, status, and is_truedy_managed fields. Use the returned id when assigning the number to an agent. Errors:

422 — The number is invalid, unavailable, or the organization’s telephony provider is not configured.
401 — The API key is missing or invalid.
429 — The request exceeded the API rate limit.

Import Number

Body: phone_number (required, E.164), provider_type (required: telnyx, twilio, plivo, or custom_sip). For Telnyx/Twilio include api_key. For custom_sip include sip_username, sip_password, sip_server. Optional provider fields include friendly_name, account_sid, auth_token, public_key, application_sid, and plivo_auth_id. 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.

API documentation

Endpoints

Telephony

Telephony

List Numbers

Search Numbers

Purchase Number

Import Number

Assign Number

Unassign Number

Delete (Release) Number

Get Agent Numbers

Get Webhook URL

List Credentials

​Telephony

​List Numbers

​Search Numbers

​Purchase Number

​Import Number

​Assign Number

​Unassign Number

​Delete (Release) Number

​Get Agent Numbers

​Get Webhook URL

​List Credentials

Telephony

List Numbers

Search Numbers

Purchase Number

Import Number

Assign Number

Unassign Number

Delete (Release) Number

Get Agent Numbers

Get Webhook URL

List Credentials