Create phone number

Buy a new phone number from Telnyx or Twilio and connect it to your agents.

POSThttps://api.tried.com.au/create-phone-number

Needs keys Buys a number from Telnyx (default) or Twilio, stores it in your workspace and provisions the LiveKit SIP trunks and dispatch rule it needs. Purchases need TELNYX_API_KEY or TWILIO_ACCOUNT_SID, and provisioning needs LiveKit (LIVEKIT_URL).

Without those keys, mock mode returns a generated number instead of buying one: AU numbers look like +61 2 5550 xxxx (the area code replaces the 2), US and CA numbers like +1 (415) 555-xxxx, and toll-free numbers use +61 1800 555 xxx (AU) or +1 833 555 xxxx. Every mock request is logged in List telephony operations.

Request#

Field	Type	Required	Description
`country_code`	string	No	ISO 3166 country, two upper-case letters. Default `AU`. Telnyx searches any country; Twilio only the countries it sells.
`area_code`	integer	No	Area code to buy in, for example `2` or `415`. Ignored for toll-free numbers.
`toll_free`	boolean	No	Buy a toll-free number. Adds 3 to the monthly price.
`phone_number`	string	No	A specific E.164 number to buy, usually one returned by Search phone numbers. Without it, the first available match is bought.
`number_provider`	string	No	`telnyx` or `twilio`. Default `telnyx`.
`nickname`	string	No	Label shown in the dashboard.
`inbound_agents`	array	No	Agents that answer inbound calls. See Agent weights. Default `[]`.
`outbound_agents`	array	No	Agents used for outbound calls from this number. Same shape. Default `[]`.
`inbound_webhook_url`	string	No	URL called with `call_inbound` before each inbound call. Must be a valid URL.
`fallback_number`	string	No	E.164 number that inbound callers are sent to when no concurrency slot frees up.
`allowed_inbound_country_list`	string[]	No	ISO country codes allowed to call in. Callers from other countries are rejected. Omit to allow all.
`allowed_outbound_country_list`	string[]	No	ISO country codes this number may dial. Omit to allow all.
`cps_limit`	number	No	Calls per second for outbound dialling, from 0.1 to 150. Without it, purchased numbers use 4.

Agent weights#

Each entry in inbound_agents and outbound_agents is an object:

Field	Type	Required	Description
`agent_id`	string	Yes	An agent in your workspace.
`agent_version`	integer	No	Pin a version. Without it, the latest version is used.
`weight`	number	Yes	Greater than 0, at most 1. Each call picks one agent at random in proportion to its weight.

Every listed agent (and version) must exist, or the request fails with 404 before anything is bought.

Example request#

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 front desk",
    "inbound_agents": [{ "agent_id": "agent_8d2f61c0a94b3e57d1f0c2a6", "weight": 1 }],
    "outbound_agents": [{ "agent_id": "agent_8d2f61c0a94b3e57d1f0c2a6", "weight": 1 }],
    "allowed_inbound_country_list": ["AU"]
  }'

const res = await fetch("https://api.tried.com.au/create-phone-number", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRIED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    country_code: "AU",
    area_code: 2,
    nickname: "Sydney front desk",
    inbound_agents: [{ agent_id: "agent_8d2f61c0a94b3e57d1f0c2a6", weight: 1 }],
    outbound_agents: [{ agent_id: "agent_8d2f61c0a94b3e57d1f0c2a6", weight: 1 }],
    allowed_inbound_country_list: ["AU"],
  }),
});
const number = await res.json();

import os, requests

res = requests.post(
    "https://api.tried.com.au/create-phone-number",
    headers={"Authorization": f"Bearer {os.environ['TRIED_API_KEY']}"},
    json={
        "country_code": "AU",
        "area_code": 2,
        "nickname": "Sydney front desk",
        "inbound_agents": [{"agent_id": "agent_8d2f61c0a94b3e57d1f0c2a6", "weight": 1}],
        "outbound_agents": [{"agent_id": "agent_8d2f61c0a94b3e57d1f0c2a6", "weight": 1}],
        "allowed_inbound_country_list": ["AU"],
    },
)
number = res.json()

Response#

201 Created

{
  "phone_number": "+61255501234",
  "phone_number_pretty": "+61 2 5550 1234",
  "nickname": "Sydney front desk",
  "provider": "telnyx",
  "inbound_agents": [{ "agent_id": "agent_8d2f61c0a94b3e57d1f0c2a6", "weight": 1 }],
  "outbound_agents": [{ "agent_id": "agent_8d2f61c0a94b3e57d1f0c2a6", "weight": 1 }],
  "inbound_webhook_url": null,
  "allowed_inbound_country_list": ["AU"],
  "allowed_outbound_country_list": null,
  "termination_uri": null,
  "sip_trunk_auth_username": null,
  "last_modification_timestamp": 1792396800000,
  "fallback_number": null,
  "transport": "TCP",
  "media_encryption": "allowed",
  "sip_trunk_id": null,
  "cps_limit": null,
  "livekit_inbound_trunk_id": "ST_4kQm8vWz2RfT",
  "livekit_outbound_trunk_id": "ST_9pLx3cHn7YbD",
  "livekit_dispatch_rule_id": "SDR_6tJe1sGa5UoK",
  "provisioning_status": "provisioned",
  "provisioning_error": null,
  "spam_flagged": false,
  "country_code": "AU",
  "monthly_price": 8
}

The number object is described field by field on Get phone number. Purchased numbers start with transport TCP and media_encryption allowed.

If provisioning fails after the purchase, the request still returns 201, with provisioning_status error and the reason in provisioning_error. Fix the cause and call Provision phone number to retry.

Errors#

Status	When
`400`	Body validation failed (for example `country_code: Invalid`), or `fallback_number must be E.164`.
`401`	Missing or invalid API key.
`403`	The key's IP allowlist or scopes reject the request. This route needs the `numbers` scope. Also returned for the member role (`The member role is read-only`) and when business verification is required and not approved (`Business verification (KYC) is ... it must be approved before you can buy numbers`).
`404`	An agent in `inbound_agents` or `outbound_agents` does not exist, for example `Agent agent_8d2f61c0a94b3e57d1f0c2a6 not found`.
`409`	The number is already in Tried: `+61255501234 already exists`.
`422`	The provider refused the search or order, for example `No Telnyx numbers available for AU area 2`.
`429`	Rate limit exceeded. See Rate limits.

See Errors for the body format.

Retell compatibility#

Same path and method as Retell, with the same agent weight objects. country_code accepts any ISO country (Retell sells US and CA numbers only) and defaults to AU.