Buying a Phone Number

Truedy-managed numbers are the fastest way to get a phone number ready for your agent. Truedy purchases the number from its carrier partner, configures all routing automatically, and adds the number to your account — no external provider dashboard required. This guide covers searching for available numbers, purchasing via the dashboard or API, assigning to an agent, and releasing numbers you no longer need.

Prerequisites

A Truedy account with an active subscription.
An API key (for API-based provisioning) — see Authentication.
At least one agent created — see Creating an Agent.

Dashboard flow

Open Phone Numbers

In the Truedy dashboard, navigate to Settings → Phone Numbers.

Click Buy Number

Click the Buy Number button in the top-right corner of the Phone Numbers page.

Select country and area code

Choose the country from the dropdown. For US/Canada numbers, optionally enter a preferred area code to narrow results. Select a number type (local, toll-free, or mobile where available).

Review available numbers

Truedy returns a list of available numbers matching your criteria. Each row shows the full number, type, and monthly cost.

Purchase

Click Buy next to the number you want. Confirm the purchase in the dialog. The number appears in your Phone Numbers list immediately.

Assign to an agent

Click the number in the list, then select an agent from the Assigned Agent dropdown and save. The number is now active for outbound and inbound calls on that agent.

API flow

Step 1 — Search available numbers

Search for numbers matching your requirements. This is a POST with a JSON body.

curl -X POST https://api.truedy.ai/api/public/v1/telephony/numbers/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "area_code": "415",
    "phone_number_type": "local",
    "page_size": 10
  }'

Request body:

Field	Type	Required	Description
`country_code`	string	No	ISO 3166-1 alpha-2 country code. Default: `US`
`area_code`	string	No	Preferred area code / NPA (US/Canada only)
`administrative_area`	string	No	State or province abbreviation (e.g. `CA`)
`locality`	string	No	City name to narrow results
`phone_number_type`	string	No	`local` (default), `toll-free`, or `mobile`
`page`	integer	No	Page number for pagination. Default: `1`
`page_size`	integer	No	Results per page. Default: `20`, max: `50`

Response includes a data array of available numbers, each with phone_number (E.164), phone_number_type, features, and cost_information.

If your preferred area code shows no results, try searching without area_code to see all available numbers in that country, then pick the closest match.

Step 2 — Purchase a number

Pass the exact phone_number from the search results to purchase it.

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"
  }'

Request body:

Field	Type	Required	Description
`phone_number`	string	Yes	E.164 number to purchase (from search results, e.g. `+14155551234`)

Response returns the created phone number object including id, phone_number, status, and is_truedy_managed: true.

Step 3 — Assign the number to an agent

After purchasing, assign the number to an agent. Specify whether it’s for inbound, outbound, or both (run the request twice).

# Assign for outbound (agent places calls from this number)
curl -X POST https://api.truedy.ai/api/public/v1/telephony/numbers/assign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number_id": "NUMBER_UUID",
    "agent_id": "AGENT_UUID",
    "assignment_type": "outbound"
  }'

# Also assign for inbound (agent receives calls on this number)
curl -X POST https://api.truedy.ai/api/public/v1/telephony/numbers/assign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number_id": "NUMBER_UUID",
    "agent_id": "AGENT_UUID",
    "assignment_type": "inbound"
  }'

Assign request body:

Field	Type	Required	Description
`number_id`	string	Yes	ID of the phone number to assign
`agent_id`	string	Yes	ID of the agent to assign the number to
`assignment_type`	string	Yes	`inbound` — agent receives calls; `outbound` — agent places calls from this number

Inbound and outbound are separate assignments. A single number can be assigned to the same (or different) agents for each direction. Run the assign request twice with "inbound" and "outbound" to enable both.

To unassign: POST /telephony/numbers/unassign with {number_id, assignment_type}.

Full end-to-end example

BASE="https://api.truedy.ai/api/public/v1"
KEY="YOUR_API_KEY"

# 1. Search
curl -s -X POST "$BASE/telephony/numbers/search" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"country_code":"US","area_code":"212","phone_number_type":"local","page_size":5}'

# 2. Purchase (use a phone_number from step 1)
curl -s -X POST "$BASE/telephony/numbers/purchase" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"+12125550123"}'

# 3. Assign for outbound (use number id from step 2)
curl -s -X POST "$BASE/telephony/numbers/assign" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"number_id":"NUMBER_UUID","agent_id":"AGENT_UUID","assignment_type":"outbound"}'

Billing

Numbers are billed on a monthly flat fee from the date of purchase.
The monthly fee renews automatically and is charged to your Truedy subscription.
Per-minute charges for calls placed or received on the number are billed separately.
All charges appear on your Truedy invoice — there is no separate carrier invoice for Truedy-managed numbers.

You can see current number pricing in the dashboard when browsing available numbers, or via the cost_information.monthly_cost field in the search API response.

US and Canada vs international availability

US and Canada have the broadest inventory. Local numbers are available in virtually all area codes. Toll-free (800, 888, 877, 866, 855, 844, 833) numbers are widely available.
UK, Australia, and major EU markets have good availability for local numbers.
Other countries vary significantly. Run a search against the API to confirm availability before building a workflow that depends on a specific country or region.

Releasing a number

When you no longer need a number, release it to stop billing. Dashboard: Settings → Phone Numbers → select the number → Release Number. API:

curl -X DELETE https://api.truedy.ai/api/public/v1/telephony/numbers/NUMBER_UUID \
  -H "Authorization: Bearer YOUR_API_KEY"

Releasing a number is immediate and irreversible. The number is returned to carrier inventory and may be reassigned to another customer. Unassign the number from all agents and campaigns before releasing it.

Next steps

Importing Phone Numbers

Bring your own Twilio or Telnyx number

Telephony Overview

Understand the full telephony model

Making Outbound Calls

Place your first call with the new number

Setting Up Inbound

Route inbound calls to your agent

​Buying a Phone Number

​Prerequisites

​Dashboard flow

​API flow

​Step 1 — Search available numbers

​Step 2 — Purchase a number

​Step 3 — Assign the number to an agent

​Full end-to-end example

​Billing

​US and Canada vs international availability

​Releasing a number

​Next steps

Importing Phone Numbers

Telephony Overview

Making Outbound Calls

Setting Up Inbound

Buying a Phone Number

Prerequisites

Dashboard flow

API flow

Step 1 — Search available numbers

Step 2 — Purchase a number

Step 3 — Assign the number to an agent

Full end-to-end example

Billing

US and Canada vs international availability

Releasing a number

Next steps