Get a phone number

A phone number gives your agent an address on the phone network. You keep your numbers with your own carrier, and your carrier bills the phone line. Tried does not charge for it.

• Connect your own number over SIP trunking. This is what the dashboard offers: a Twilio number on your own Twilio Elastic SIP trunk, or a number from any carrier or PBX. See Custom telephony and Twilio.
• Buy a number through the API (POST /create-phone-number). This is not offered today: the endpoint exists for Retell compatibility and is documented below for reference, but Tried does not sell numbers or charge for phone lines.

Either way, the number ends up in the Phone Numbers list with the same settings: inbound and outbound agents, inbound webhook, country allow lists, version binding, fallback number and calls per second.

Connect a number in the dashboard#

Buy a number through the API#

POST /create-phone-number searches the provider for an available number, orders it, stores it in your workspace and provisions it. It returns HTTP 201 with the phone number object.

curl -X POST https://api.tried.com.au/create-phone-number \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "AU",
    "area_code": 2,
    "nickname": "Sydney reception",
    "inbound_agents": [{ "agent_id": "agent_8e0c...", "weight": 1 }],
    "fallback_number": "+61290000000"
  }'

AgentWeight is { agent_id: string, agent_version?: integer, weight: number } with weight greater than 0 and at most 1.

Search before you buy#

GET /search-phone-numbers lists numbers you can buy, with the monthly price. Pick one and pass it as phone_number to POST /create-phone-number.

[
  {
    "phone_number": "+61255501234",
    "country_code": "AU",
    "toll_free": false,
    "monthly_price": 8,
    "features": ["voice", "sms"]
  }
]

Telnyx results use the carrier's monthly_cost when it returns one. Otherwise, and for Twilio, the price comes from the Tried price list below.

Number types#

In mock mode (no TELNYX_API_KEY, or no TWILIO_ACCOUNT_SID for Twilio) the API returns fake numbers in the formats above and records the purchase in the provider operation log. With keys, Telnyx orders through POST /v2/number_orders and Twilio through IncomingPhoneNumbers.

What happens after a purchase#

1. The number is stored with provider (telnyx or twilio), country_code and provisioning_status: "pending".
2. Telnyx: on the first purchase Tried creates an outbound voice profile and an FQDN connection that points at your LiveKit SIP host (unless TELNYX_CONNECTION_ID is set), then assigns the number to it. See Telnyx.
3. Twilio: Tried creates one Elastic SIP trunk per workspace on the platform Twilio account, with an origination URL pointing at LiveKit SIP, and attaches the number.
4. LiveKit inbound and outbound trunks and a dispatch rule are created for the number. provisioning_status becomes provisioned, or error with provisioning_error set. POST /provision-phone-number/:n retries.

Release a number#

In the dashboard, open the number, click the ... menu and Delete number. With the API, call DELETE /delete-phone-number/:n. Tried deletes the LiveKit trunks and dispatch rule and, for bought Telnyx and Twilio numbers, releases the number back to the carrier. An imported number is only removed from Tried; it stays on your carrier account.

Limits and gotchas#

• Buying needs a business profile when TRIED_KYC_REQUIRED=1. Until POST /kyc is approved, POST /create-phone-number returns 403.
• Many countries (Australia included) require a regulatory bundle with an address and identity documents before a carrier sells you a number. Create it in the Telnyx or Twilio portal first. A refused order returns HTTP 422 with the carrier's message.
• fallback_number must be E.164, otherwise the API returns 400.
• A number can belong to only one workspace. Buying or importing a number that already exists returns 409.
• The dashboard does not have a buy dialog. Buying runs through the API.

Related#

• Import phone number API
• Create phone number API
• International calling