Update Phone Number

PATCH

organization-phone-numbers

{id}

Update a phone number

curl --request PATCH \
  --url https://api.dialnexa.com/organization-phone-numbers/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "country_iso": "91",
  "phone_number": 1234567890,
  "telephony_provider_id": "prov_xxxxxx",
  "status": "active",
  "inbound_agent_id": "A1B2C3D4E5F6G7",
  "outbound_agent_id": "B1C2D3E4F5G6H7",
  "inbound_agent_version_number": 1,
  "outbound_agent_version_number": 2,
  "sip_trunk_enabled": false,
  "rental_start_date": "2026-04-07",
  "rental_end_date": "2026-05-07",
  "rental_status": "active",
  "nickname": "Sales Line"
}
'

import requests

url = "https://api.dialnexa.com/organization-phone-numbers/{id}"

payload = {
    "country_iso": "91",
    "phone_number": 1234567890,
    "telephony_provider_id": "prov_xxxxxx",
    "status": "active",
    "inbound_agent_id": "A1B2C3D4E5F6G7",
    "outbound_agent_id": "B1C2D3E4F5G6H7",
    "inbound_agent_version_number": 1,
    "outbound_agent_version_number": 2,
    "sip_trunk_enabled": False,
    "rental_start_date": "2026-04-07",
    "rental_end_date": "2026-05-07",
    "rental_status": "active",
    "nickname": "Sales Line"
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'x-organization-id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    country_iso: '91',
    phone_number: 1234567890,
    telephony_provider_id: 'prov_xxxxxx',
    status: 'active',
    inbound_agent_id: 'A1B2C3D4E5F6G7',
    outbound_agent_id: 'B1C2D3E4F5G6H7',
    inbound_agent_version_number: 1,
    outbound_agent_version_number: 2,
    sip_trunk_enabled: false,
    rental_start_date: '2026-04-07',
    rental_end_date: '2026-05-07',
    rental_status: 'active',
    nickname: 'Sales Line'
  })
};

fetch('https://api.dialnexa.com/organization-phone-numbers/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/organization-phone-numbers/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'country_iso' => '91',
    'phone_number' => 1234567890,
    'telephony_provider_id' => 'prov_xxxxxx',
    'status' => 'active',
    'inbound_agent_id' => 'A1B2C3D4E5F6G7',
    'outbound_agent_id' => 'B1C2D3E4F5G6H7',
    'inbound_agent_version_number' => 1,
    'outbound_agent_version_number' => 2,
    'sip_trunk_enabled' => false,
    'rental_start_date' => '2026-04-07',
    'rental_end_date' => '2026-05-07',
    'rental_status' => 'active',
    'nickname' => 'Sales Line'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-id: <x-organization-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/organization-phone-numbers/{id}"

	payload := strings.NewReader("{\n  \"country_iso\": \"91\",\n  \"phone_number\": 1234567890,\n  \"telephony_provider_id\": \"prov_xxxxxx\",\n  \"status\": \"active\",\n  \"inbound_agent_id\": \"A1B2C3D4E5F6G7\",\n  \"outbound_agent_id\": \"B1C2D3E4F5G6H7\",\n  \"inbound_agent_version_number\": 1,\n  \"outbound_agent_version_number\": 2,\n  \"sip_trunk_enabled\": false,\n  \"rental_start_date\": \"2026-04-07\",\n  \"rental_end_date\": \"2026-05-07\",\n  \"rental_status\": \"active\",\n  \"nickname\": \"Sales Line\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("x-organization-id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.dialnexa.com/organization-phone-numbers/{id}")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country_iso\": \"91\",\n  \"phone_number\": 1234567890,\n  \"telephony_provider_id\": \"prov_xxxxxx\",\n  \"status\": \"active\",\n  \"inbound_agent_id\": \"A1B2C3D4E5F6G7\",\n  \"outbound_agent_id\": \"B1C2D3E4F5G6H7\",\n  \"inbound_agent_version_number\": 1,\n  \"outbound_agent_version_number\": 2,\n  \"sip_trunk_enabled\": false,\n  \"rental_start_date\": \"2026-04-07\",\n  \"rental_end_date\": \"2026-05-07\",\n  \"rental_status\": \"active\",\n  \"nickname\": \"Sales Line\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/organization-phone-numbers/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["x-organization-id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country_iso\": \"91\",\n  \"phone_number\": 1234567890,\n  \"telephony_provider_id\": \"prov_xxxxxx\",\n  \"status\": \"active\",\n  \"inbound_agent_id\": \"A1B2C3D4E5F6G7\",\n  \"outbound_agent_id\": \"B1C2D3E4F5G6H7\",\n  \"inbound_agent_version_number\": 1,\n  \"outbound_agent_version_number\": 2,\n  \"sip_trunk_enabled\": false,\n  \"rental_start_date\": \"2026-04-07\",\n  \"rental_end_date\": \"2026-05-07\",\n  \"rental_status\": \"active\",\n  \"nickname\": \"Sales Line\"\n}"

response = http.request(request)
puts response.read_body

{
  "sip_trunk_enabled": false
}

Legacy endpoint - deprecated. Unversioned endpoints are scheduled for removal on July 31, 2026. There is no public /v1 replacement documented for updating a phone number yet. Keep existing integrations on this endpoint until DialNexa publishes a replacement.

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

Parameter	Description
`id`	The phone number ID, for example `phn_f7w2kx5mb9qz`.

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.

Get Phone Number: confirm new values.
Buy a Phone Number: purchase a new number.
Release a Number: return the number to the provider’s pool.
Receive Inbound Calls: end-to-end inbound setup guide.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-organization-id

string

required

RSA-encrypted organization_id string (base64 format)

Path Parameters

string

required

Body

application/json

country_iso

string

Country calling code digits only (e.g. "91" for India, "1" for US); stored as VARCHAR(3)

Example:

"91"

phone_number

number

Phone number assigned to organization (without country code)

Example:

1234567890

telephony_provider_id

string

ID of telephony provider (14-char string)

Example:

"prov_xxxxxx"

status

enum<string>

Status of the phone number

Available options:

pending,

active

Example:

"active"

inbound_agent_id

string

Inbound agent ID

Example:

"A1B2C3D4E5F6G7"

outbound_agent_id

string

Outbound agent ID

Example:

"B1C2D3E4F5G6H7"

inbound_agent_version_number

number

Inbound agent version number

Example:

1

outbound_agent_version_number

number

Outbound agent version number

Example:

2

sip_trunk_enabled

boolean

default:false

When true, Speech IO uses SIP trunking (e.g. asterisk) for this number.

rental_start_date

string

Rental start date in YYYY-MM-DD format

Example:

"2026-04-07"

rental_end_date

string

Rental end date in YYYY-MM-DD format

Example:

"2026-05-07"

rental_status

enum<string>

Rental lifecycle status for this phone number

Available options:

active,

expired,

available_for_reassignment

Example:

"active"

nickname

string

Human-readable nickname for this phone number

Example:

"Sales Line"

Response

Phone number updated.

sip_trunk_enabled

boolean

default:false

required

When true, Speech IO uses SIP trunking (e.g. asterisk) for this number.

Release a NumberRelease a purchased phone number from your account and stop billing for it at the end of the current cycle.

Update a phone number

curl --request PATCH \
  --url https://api.dialnexa.com/organization-phone-numbers/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "country_iso": "91",
  "phone_number": 1234567890,
  "telephony_provider_id": "prov_xxxxxx",
  "status": "active",
  "inbound_agent_id": "A1B2C3D4E5F6G7",
  "outbound_agent_id": "B1C2D3E4F5G6H7",
  "inbound_agent_version_number": 1,
  "outbound_agent_version_number": 2,
  "sip_trunk_enabled": false,
  "rental_start_date": "2026-04-07",
  "rental_end_date": "2026-05-07",
  "rental_status": "active",
  "nickname": "Sales Line"
}
'

import requests

url = "https://api.dialnexa.com/organization-phone-numbers/{id}"

payload = {
    "country_iso": "91",
    "phone_number": 1234567890,
    "telephony_provider_id": "prov_xxxxxx",
    "status": "active",
    "inbound_agent_id": "A1B2C3D4E5F6G7",
    "outbound_agent_id": "B1C2D3E4F5G6H7",
    "inbound_agent_version_number": 1,
    "outbound_agent_version_number": 2,
    "sip_trunk_enabled": False,
    "rental_start_date": "2026-04-07",
    "rental_end_date": "2026-05-07",
    "rental_status": "active",
    "nickname": "Sales Line"
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {
    'x-organization-id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    country_iso: '91',
    phone_number: 1234567890,
    telephony_provider_id: 'prov_xxxxxx',
    status: 'active',
    inbound_agent_id: 'A1B2C3D4E5F6G7',
    outbound_agent_id: 'B1C2D3E4F5G6H7',
    inbound_agent_version_number: 1,
    outbound_agent_version_number: 2,
    sip_trunk_enabled: false,
    rental_start_date: '2026-04-07',
    rental_end_date: '2026-05-07',
    rental_status: 'active',
    nickname: 'Sales Line'
  })
};

fetch('https://api.dialnexa.com/organization-phone-numbers/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/organization-phone-numbers/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'country_iso' => '91',
    'phone_number' => 1234567890,
    'telephony_provider_id' => 'prov_xxxxxx',
    'status' => 'active',
    'inbound_agent_id' => 'A1B2C3D4E5F6G7',
    'outbound_agent_id' => 'B1C2D3E4F5G6H7',
    'inbound_agent_version_number' => 1,
    'outbound_agent_version_number' => 2,
    'sip_trunk_enabled' => false,
    'rental_start_date' => '2026-04-07',
    'rental_end_date' => '2026-05-07',
    'rental_status' => 'active',
    'nickname' => 'Sales Line'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-id: <x-organization-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/organization-phone-numbers/{id}"

	payload := strings.NewReader("{\n  \"country_iso\": \"91\",\n  \"phone_number\": 1234567890,\n  \"telephony_provider_id\": \"prov_xxxxxx\",\n  \"status\": \"active\",\n  \"inbound_agent_id\": \"A1B2C3D4E5F6G7\",\n  \"outbound_agent_id\": \"B1C2D3E4F5G6H7\",\n  \"inbound_agent_version_number\": 1,\n  \"outbound_agent_version_number\": 2,\n  \"sip_trunk_enabled\": false,\n  \"rental_start_date\": \"2026-04-07\",\n  \"rental_end_date\": \"2026-05-07\",\n  \"rental_status\": \"active\",\n  \"nickname\": \"Sales Line\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("x-organization-id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.dialnexa.com/organization-phone-numbers/{id}")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"country_iso\": \"91\",\n  \"phone_number\": 1234567890,\n  \"telephony_provider_id\": \"prov_xxxxxx\",\n  \"status\": \"active\",\n  \"inbound_agent_id\": \"A1B2C3D4E5F6G7\",\n  \"outbound_agent_id\": \"B1C2D3E4F5G6H7\",\n  \"inbound_agent_version_number\": 1,\n  \"outbound_agent_version_number\": 2,\n  \"sip_trunk_enabled\": false,\n  \"rental_start_date\": \"2026-04-07\",\n  \"rental_end_date\": \"2026-05-07\",\n  \"rental_status\": \"active\",\n  \"nickname\": \"Sales Line\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/organization-phone-numbers/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["x-organization-id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"country_iso\": \"91\",\n  \"phone_number\": 1234567890,\n  \"telephony_provider_id\": \"prov_xxxxxx\",\n  \"status\": \"active\",\n  \"inbound_agent_id\": \"A1B2C3D4E5F6G7\",\n  \"outbound_agent_id\": \"B1C2D3E4F5G6H7\",\n  \"inbound_agent_version_number\": 1,\n  \"outbound_agent_version_number\": 2,\n  \"sip_trunk_enabled\": false,\n  \"rental_start_date\": \"2026-04-07\",\n  \"rental_end_date\": \"2026-05-07\",\n  \"rental_status\": \"active\",\n  \"nickname\": \"Sales Line\"\n}"

response = http.request(request)
puts response.read_body

{
  "sip_trunk_enabled": false
}

Overview

Endpoints - v1

Endpoints - Legacy

Code Examples And SDK Status

When to use this

Path parameters

Errors

Authorizations

Headers

Path Parameters

Body

Response

​When to use this

​Path parameters

​Errors

​Related endpoints

Authorizations

Headers

Path Parameters

Body

Response

When to use this

Path parameters

Errors

Related endpoints