Update a phone number

PUT /api/v1/organizations/telephony-configs/{config_id}/phone-numbers/{phone_number_id}

Partial update of a registered number — the common use is swapping the inbound agent on a live DID. Every update re-runs the provider sync so the inbound webhook stays pointed at the right place.

address is immutable

You can't change address on an existing number — delete it and add a new one. Everything else (label, inbound target, active flag, country code, metadata) is mutable.

Request body

All fields optional:

Field	Type	Description
`label`	string (≤64)	Rename.
`inbound_agent_uuid`	string	Point inbound calls at a different saved agent — its public `uuid`.
`clear_inbound_target`	bool	Set `true` to detach the inbound agent entirely. Can't be combined with `inbound_agent_uuid`.
`is_active`	bool	Enable/disable the number.
`country_code`	string (ISO-2)	Correct the country hint.
`extra_metadata`	object	Replace the metadata blob.

Response

200 OK — the updated number, including a provider_sync object (see add-number).

Examples

Swap the inbound agent

curl -X PUT https://dashboard.zoxa.ai/api/v1/organizations/telephony-configs/7/phone-numbers/88 \
  -H "X-API-Key: zsk_..." \
  -H "Content-Type: application/json" \
  -d '{ "inbound_agent_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }'

import httpx
httpx.put(
    "https://dashboard.zoxa.ai/api/v1/organizations/telephony-configs/7/phone-numbers/88",
    headers={"X-API-Key": "zsk_..."},
    json={"inbound_agent_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7"},
)

Detach inbound routing

curl -X PUT https://dashboard.zoxa.ai/api/v1/organizations/telephony-configs/7/phone-numbers/88 \
  -H "X-API-Key: zsk_..." \
  -H "Content-Type: application/json" \
  -d '{ "clear_inbound_target": true }'

Editing the agent itself needs no re-bind

To change what the agent says or does, edit the agent with PATCH /agents/{agent_uuid} — the binding still points at it, and the new config is resolved fresh on the next inbound call. Use this endpoint (update-number) only to point the number at a different agent.

Errors

Status	`detail`	When
`400`	`"Cannot set clear_inbound_target with an inbound target ID"`	`clear_inbound_target` sent together with `inbound_agent_uuid`.
`404`	`"Telephony configuration not found"`	`config_id` not in your org.
`404`	`"Phone number not found"`	`phone_number_id` not under this config.
`404`	`"Agent not found"`	`inbound_agent_uuid` doesn't resolve in your org.