Attach Agent Phone Number

POST

agents

{agentId}

phone-numbers

curl --request POST \
  --url https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number_id": "phn_abc123",
  "direction": "outbound"
}
'

import requests

url = "https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers"

payload = {
    "phone_number_id": "phn_abc123",
    "direction": "outbound"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({phone_number_id: 'phn_abc123', direction: 'outbound'})
};

fetch('https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers', 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/v1/agents/{agentId}/phone-numbers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'phone_number_id' => 'phn_abc123',
    'direction' => 'outbound'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/v1/agents/{agentId}/phone-numbers"

	payload := strings.NewReader("{\n  \"phone_number_id\": \"phn_abc123\",\n  \"direction\": \"outbound\"\n}")

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

	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.post("https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number_id\": \"phn_abc123\",\n  \"direction\": \"outbound\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number_id\": \"phn_abc123\",\n  \"direction\": \"outbound\"\n}"

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

{
  "success": true,
  "error": false,
  "statusCode": 201,
  "message": "Success",
  "data": {
    "id": "k2m9q4wz1abcde",
    "direction": "outbound",
    "linked_at": "2026-09-30T06:00:00.000Z",
    "linked_by": null,
    "unlinked_at": null,
    "unlinked_by": null,
    "unlink_reason": null,
    "agent_id": "agent_2g7Xy3tY53gRlp",
    "phone_number_id": "phn_abc123"
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Changes state - verify before retry Attach an agent phone number to route calls through that agent. Choose inbound so the number rings the agent, or outbound so the agent can call from it. The link belongs to the agent, not to a version: every version uses it, inbound calls run on the latest published version, and calls and batches pick the version they dial with.

Before you begin

Publish at least one version of the agent with Update Agent. An agent with no published version cannot take a number.
Get the number’s phn_ ID from List Phone Numbers, Buy Phone Number, or Link SIP Trunk.
Check List Agent Phone Numbers. An agent can have at most three inbound and three outbound numbers.

Limits

Rule	Detail
Numbers per direction	Up to 3 inbound and 3 outbound numbers per agent.
One agent per direction	A number can ring one agent and be dialed from by one agent. The two can be different agents.
Default numbers	DialNexa’s shared default number cannot be attached for inbound calls.
SIP trunk numbers	Not allowed on a Conversational Flow agent whose latest published version has a call transfer node.

Attach agent phone number request

curl -X POST "https://api.dialnexa.com/v1/agents/agent_2g7Xy3tY53gRlp/phone-numbers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number_id": "phn_abc123",
    "direction": "outbound"
  }'

Verify the result

A 201 response returns the new link in data, with linked_at set and unlinked_at null. Call List Agent Phone Numbers to confirm the number appears under the chosen direction. Once an agent has two or more outbound numbers, Create Call and Create Batch Call need phone_number_id to choose one.

Errors and recovery

Refusals carry a code in data.code.

Status	Code	Cause and fix
`400`	`AGENT_NOT_PUBLISHED`	The agent has no published version. Publish one, then retry.
`400`	`PHONE_NUMBER_LIMIT_REACHED`	The agent already has 3 numbers in this direction (`data.limit`). Detach one first.
`400`	none	The body is invalid, or a SIP trunk number was sent for a Conversational Flow agent with a call transfer node.
`403`	`DEFAULT_NUMBER_NOT_ALLOWED_INBOUND`	DialNexa’s shared default number was sent with `direction: "inbound"`. Use another number.
`404`	none	The agent or the phone number is not in this workspace.
`409`	`PHONE_NUMBER_ALREADY_LINKED`	The number is already linked to this agent in this direction. Nothing to do.
`409`	`PHONE_NUMBER_LINKED_TO_OTHER_AGENT`	Another agent holds the number in this direction (`data.agent_id`, `data.agent_title`). Detach it from that agent first, or send `move: true` after confirming that it should lose the number.

If a request times out, list the agent’s numbers before retrying. A repeat of a request that succeeded returns 409 PHONE_NUMBER_ALREADY_LINKED and changes nothing.

Move a number from another agent

Add "move": true to the attach request to move the number in the chosen direction. The old agent loses that direction and the new agent receives it in one transaction. The opposite direction stays unchanged. The old link is closed with unlink_reason: "manual". Live calls on the number block either direction with 409 PHONE_NUMBER_HAS_LIVE_CALLS. For an outbound move, unfinished batches return NUMBER_USED_BY_BATCH and active workflows return PHONE_NUMBER_USED_IN_ACTIVE_WORKFLOWS. Change the affected batches’ number or cancel them, pause the affected workflows, and wait for calls to finish before retrying. If the request times out, check both agents’ number lists and link history before sending it again.

Authorizations

Authorization

string

header

required

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

Path Parameters

agentId

string

required

Agent ID from List Agents.

Example:

"agent_2g7Xy3tY53gRlp"

Body

application/json

phone_number_id

string

required

Organization phone number to attach

Example:

"phn_2g7Xy3tY53gRlp"

direction

enum<string>

required

Available options:

inbound,

outbound

move

boolean

default:false

Move the number here when another agent holds it in this direction. That agent loses it in the same request, under the same rules as detaching it there.

Response

Successful response.

success

boolean

required

error

boolean

required

statusCode

integer

required

message

string

required

data

object

required

Show child attributes

timestamp

string<date-time>

required

Attach Agent Phone Number

curl --request POST \
  --url https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number_id": "phn_abc123",
  "direction": "outbound"
}
'

import requests

url = "https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers"

payload = {
    "phone_number_id": "phn_abc123",
    "direction": "outbound"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({phone_number_id: 'phn_abc123', direction: 'outbound'})
};

fetch('https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers', 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/v1/agents/{agentId}/phone-numbers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'phone_number_id' => 'phn_abc123',
    'direction' => 'outbound'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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/v1/agents/{agentId}/phone-numbers"

	payload := strings.NewReader("{\n  \"phone_number_id\": \"phn_abc123\",\n  \"direction\": \"outbound\"\n}")

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

	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.post("https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number_id\": \"phn_abc123\",\n  \"direction\": \"outbound\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/agents/{agentId}/phone-numbers")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number_id\": \"phn_abc123\",\n  \"direction\": \"outbound\"\n}"

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

{
  "success": true,
  "error": false,
  "statusCode": 201,
  "message": "Success",
  "data": {
    "id": "k2m9q4wz1abcde",
    "direction": "outbound",
    "linked_at": "2026-09-30T06:00:00.000Z",
    "linked_by": null,
    "unlinked_at": null,
    "unlinked_by": null,
    "unlink_reason": null,
    "agent_id": "agent_2g7Xy3tY53gRlp",
    "phone_number_id": "phn_abc123"
  },
  "timestamp": "2026-09-07T06:00:00.000Z"
}

Overview

Endpoints

Before you begin

Limits

Attach agent phone number request

Verify the result

Errors and recovery

Move a number from another agent

Authorizations

Path Parameters

Body

Response

​Before you begin

​Limits

​Attach agent phone number request

​Verify the result

​Errors and recovery

​Move a number from another agent

​Related endpoints

Authorizations

Path Parameters

Body

Response

Before you begin

Limits

Attach agent phone number request

Verify the result

Errors and recovery

Move a number from another agent

Related endpoints