Skip to main content
PATCH
/
organization-phone-numbers
/
{id}
Update a phone number
curl --request PATCH \
  --url https://api.dialnexa.com/v1/organization-phone-numbers/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_id": "<string>",
  "label": "<string>",
  "nickname": "Support Line"
}
'
{
  "id": "phn_abc123",
  "phone_number": "+912234567890",
  "label": "Main Support Line",
  "agent_id": "agt_abc123",
  "status": "active",
  "provider": "twilio",
  "created_at": "2024-03-01T10:00:00.000Z",
  "nickname": "Sales Line"
}
Updates editable fields on a phone number provisioned on your workspace. The most common change is assigning or replacing the inbound agent; you can also set or clear the display nickname so the number is easier to identify in dashboard selectors. Only the fields you include are updated, omitted fields keep their current values. This endpoint does not change the underlying carrier configuration, the E.164 number itself, or the monthly billing.

​
When to use this

  • Assigning an agent for the first time after purchasing the number through Buy a Phone Number.
  • Switching the inbound agent when handing the number to a different team or workflow.
  • Renaming for clarity: set a nickname so dashboard users can pick the right number out of a long list.
  • Detaching routing: pass agent_id: null to stop routing inbound calls without releasing the number. Useful while you investigate an issue or while the new agent is being prepared.
To release the number entirely, use Release a Number instead.

​
Path parameters

ParameterDescription
idThe phone number ID, for example phn_f7w2kx5mb9qz.

​
Body parameters

FieldDescription
agent_idNew inbound agent ID, or null to detach.
nicknameNew display nickname. Pass null or empty string to clear.
labelFree-form label for internal accounting.

​
Request example

{
  "agent_id": "agt_abc123",
  "label": "Support Line - Mumbai",
  "nickname": "Mumbai Support"
}

​
Errors

  • 404 Not Found is returned when the phone number does not exist on this workspace.
  • 400 Bad Request is returned when the supplied agent_id does not exist or is not eligible to be assigned to a number.

​
Request

curl -X PATCH "https://api.dialnexa.com/v1/organization-phone-numbers/phn_f7w2kx5mb9qz" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agt_k7m2nq9xw4p8", "nickname": "Mumbai Support"}'

​
Response

{
  "id": "phn_f7w2kx5mb9qz",
  "phone_number": "+912234567890",
  "country_code": "IN",
  "type": "local",
  "monthly_cost_usd": "1.15",
  "capabilities": ["voice"],
  "nickname": "Mumbai Support",
  "inbound_agent_id": "agt_k7m2nq9xw4p8",
  "created_at": "2024-01-15T07:00:00.000Z"
}

Authorizations

​
Authorization
string
header
required

Pass your API key as a Bearer token in the Authorization header.

Path Parameters

​
id
string
required

Body

application/json
​
agent_id
string

Assign an agent to handle inbound calls on this number.

​
label
string

Friendly label for this number.

​
nickname
string | null

Human-readable nickname for this phone number. Send null or an empty value to clear it.

Maximum string length: 255
Example:

"Support Line"

Response

Success.

​
id
string
Example:

"phn_abc123"

​
phone_number
string
Example:

"+912234567890"

​
label
string | null
Example:

"Main Support Line"

​
agent_id
string | null
Example:

"agt_abc123"

​
status
enum<string>

Phone number provisioning status.

Available options:
pending,
active
Example:

"active"

​
provider
string
Example:

"twilio"

​
created_at
string<date-time>
Example:

"2024-03-01T10:00:00.000Z"

​
nickname
string | null

Human-readable nickname shown in dashboard selectors and phone number tables.

Maximum string length: 255
Example:

"Sales Line"