Skip to content
TriedDocs
Phone numbers

Update phone number

Change a number's agents, webhook, country lists, SIP settings or call rate.

PATCHhttps://api.tried.com.au/update-phone-number/{n}

Updates the fields you send and leaves the rest unchanged. Changes to the SIP configuration re-provision the number's LiveKit trunks in the same request.

Request#

Path parameter Type Required Description
n string Yes The number in E.164, with + encoded as %2B.

All body fields are optional.

Field Type Required Description
nickname string or null No Label shown in the dashboard.
inbound_agents array No Replaces the weighted inbound agents. See Agent weights.
outbound_agents array No Replaces the weighted outbound agents.
inbound_webhook_url string or null No URL for call_inbound. null removes it.
allowed_inbound_country_list string[] or null No ISO country codes allowed to call in. null allows all.
allowed_outbound_country_list string[] or null No ISO country codes this number may dial. null allows all.
fallback_number string or null No E.164 overflow number. null removes it.
termination_uri string No Outbound destination for imported numbers.
sip_trunk_auth_username string or null No Outbound digest username.
sip_trunk_auth_password string or null No Outbound digest password. Stored encrypted.
transport string No TCP, UDP or TLS.
media_encryption string No disabled, allowed or required.
sip_trunk_id string or null No Attach the number to a workspace SIP trunk, or null to detach it.
allowed_inbound_addresses string[] No Source IPs or CIDRs allowed to send inbound INVITEs.
cps_limit number or null No Outbound calls per second, 0.1 to 150. null restores the default.

What triggers re-provisioning#

A change to termination_uri, transport, media_encryption or sip_trunk_id, or any value sent for sip_trunk_auth_username, sip_trunk_auth_password or allowed_inbound_addresses, re-provisions the number. Moving between a shared trunk and per-number trunks first deletes the old LiveKit resources. Agent, webhook, country, nickname, fallback and CPS changes take effect without re-provisioning.

Needs keys Re-provisioning talks to LiveKit SIP and needs LIVEKIT_URL. Without it, mock mode records the requests in List telephony operations.

Example request#

curl -X PATCH https://api.tried.com.au/update-phone-number/%2B61255501234 \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inbound_agents": [
      { "agent_id": "agent_8d2f61c0a94b3e57d1f0c2a6", "weight": 0.8 },
      { "agent_id": "agent_41b7e9d3c05a2f68e1d94b70", "weight": 0.2 }
    ],
    "fallback_number": "+61290001234",
    "allowed_inbound_country_list": null
  }'
const n = encodeURIComponent("+61255501234");
const res = await fetch(`https://api.tried.com.au/update-phone-number/${n}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.TRIED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    inbound_agents: [
      { agent_id: "agent_8d2f61c0a94b3e57d1f0c2a6", weight: 0.8 },
      { agent_id: "agent_41b7e9d3c05a2f68e1d94b70", weight: 0.2 },
    ],
    fallback_number: "+61290001234",
    allowed_inbound_country_list: null,
  }),
});
const number = await res.json();
import os, requests
from urllib.parse import quote

res = requests.patch(
    f"https://api.tried.com.au/update-phone-number/{quote('+61255501234')}",
    headers={"Authorization": f"Bearer {os.environ['TRIED_API_KEY']}"},
    json={
        "inbound_agents": [
            {"agent_id": "agent_8d2f61c0a94b3e57d1f0c2a6", "weight": 0.8},
            {"agent_id": "agent_41b7e9d3c05a2f68e1d94b70", "weight": 0.2},
        ],
        "fallback_number": "+61290001234",
        "allowed_inbound_country_list": None,
    },
)
number = res.json()

Response#

200 OK

The updated number. See Get phone number for every field.

{
  "phone_number": "+61255501234",
  "phone_number_pretty": "+61 2 5550 1234",
  "nickname": "Sydney front desk",
  "provider": "telnyx",
  "inbound_agents": [
    { "agent_id": "agent_8d2f61c0a94b3e57d1f0c2a6", "weight": 0.8 },
    { "agent_id": "agent_41b7e9d3c05a2f68e1d94b70", "weight": 0.2 }
  ],
  "outbound_agents": [{ "agent_id": "agent_8d2f61c0a94b3e57d1f0c2a6", "weight": 1 }],
  "inbound_webhook_url": null,
  "allowed_inbound_country_list": null,
  "allowed_outbound_country_list": null,
  "termination_uri": null,
  "sip_trunk_auth_username": null,
  "last_modification_timestamp": 1792404000000,
  "fallback_number": "+61290001234",
  "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
}

A failed re-provision still returns 200, with provisioning_status error and the reason in provisioning_error.

Errors#

Status When
400 Body validation failed (for example cps_limit: Number must be less than or equal to 150), 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. Members get The member role is read-only.
404 Phone number ... not found, an agent does not exist (Agent ... not found), or SIP trunk ... not found.
429 Rate limit exceeded. See Rate limits.

See Errors for the body format.

Retell compatibility#

Same path and method as Retell.