Attach Numbers to Agent
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/inbound/attach \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"inbound_numbers": [
"<string>"
]
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/inbound/attach"
payload = { "inbound_numbers": ["<string>"] }
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({inbound_numbers: ['<string>']})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/inbound/attach', 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.bland.ai/v2/agents/{agent_id}/inbound/attach",
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([
'inbound_numbers' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$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.bland.ai/v2/agents/{agent_id}/inbound/attach"
payload := strings.NewReader("{\n \"inbound_numbers\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
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.bland.ai/v2/agents/{agent_id}/inbound/attach")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"inbound_numbers\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/inbound/attach")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"inbound_numbers\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"agent_id": "56ad3ffc-41c3-4466-b41f-220d17779a74",
"persona_id": "4cbdee81-f067-4fb7-8738-0995316ab3ce",
"pathway_id": "48e86cb8-4d1a-4be6-a85a-4c277255eeb4",
"compiled_from_version": "4adbe770-fc45-42ea-aa17-7533429c34f3",
"attached": [
"+18005551234",
"+18005556789"
]
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "INVALID_INBOUND_NUMBERS",
"message": "Some phone numbers were not found or do not belong to you"
}
]
}
{
"data": null,
"errors": [
{
"error": "INVALID_BODY",
"message": "inbound_numbers must be a non-empty array of phone numbers"
}
]
}
{
"data": null,
"errors": [
{
"error": "NO_VERSIONS",
"message": "Agent has no saved versions — save it in the builder first"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Phone Numbers
Attach Numbers to Agent
Route inbound calls on your phone numbers to an agent.
POST
/
v2
/
agents
/
{agent_id}
/
inbound
/
attach
Attach Numbers to Agent
curl --request POST \
--url https://api.bland.ai/v2/agents/{agent_id}/inbound/attach \
--header 'Content-Type: application/json' \
--header 'authorization: <authorization>' \
--data '
{
"inbound_numbers": [
"<string>"
]
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/inbound/attach"
payload = { "inbound_numbers": ["<string>"] }
headers = {
"authorization": "<authorization>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
body: JSON.stringify({inbound_numbers: ['<string>']})
};
fetch('https://api.bland.ai/v2/agents/{agent_id}/inbound/attach', 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.bland.ai/v2/agents/{agent_id}/inbound/attach",
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([
'inbound_numbers' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"authorization: <authorization>"
],
]);
$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.bland.ai/v2/agents/{agent_id}/inbound/attach"
payload := strings.NewReader("{\n \"inbound_numbers\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("authorization", "<authorization>")
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.bland.ai/v2/agents/{agent_id}/inbound/attach")
.header("authorization", "<authorization>")
.header("Content-Type", "application/json")
.body("{\n \"inbound_numbers\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.bland.ai/v2/agents/{agent_id}/inbound/attach")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"inbound_numbers\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"data": {
"agent_id": "56ad3ffc-41c3-4466-b41f-220d17779a74",
"persona_id": "4cbdee81-f067-4fb7-8738-0995316ab3ce",
"pathway_id": "48e86cb8-4d1a-4be6-a85a-4c277255eeb4",
"compiled_from_version": "4adbe770-fc45-42ea-aa17-7533429c34f3",
"attached": [
"+18005551234",
"+18005556789"
]
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "INVALID_INBOUND_NUMBERS",
"message": "Some phone numbers were not found or do not belong to you"
}
]
}
{
"data": null,
"errors": [
{
"error": "INVALID_BODY",
"message": "inbound_numbers must be a non-empty array of phone numbers"
}
]
}
{
"data": null,
"errors": [
{
"error": "NO_VERSIONS",
"message": "Agent has no saved versions — save it in the builder first"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Overview
Points one or more of your phone numbers at the agent so inbound calls run it. Any existing pathway or persona assignment on those numbers is replaced. Calls answer with the agent’sproduction version once one is promoted; until then they run the newest version saved on the dev timeline at the time of the attach, so re-attach after saving to refresh it. The agent must have at least one saved version. Use Detach Numbers from Agent to undo.
Requires an admin, owner, operator, or prompter role.
Headers
string
required
Your API key for authentication.
Path Parameters
string
required
The agent’s unique identifier.
Body Parameters
string[]
required
Phone numbers to attach, each exactly as it appears on your account (for example
+18005551234). Must be a non-empty array of non-empty strings; surrounding whitespace is trimmed. Returns 400 INVALID_BODY if the array is missing, empty, or contains a non-string. Returns 400 INVALID_INBOUND_NUMBERS if any number is not on your account, in which case nothing is attached.Response
string
The agent ID from the request path.
string
ID of the persona the attached numbers route through. Created on the agent’s first attach and reused afterwards.
string
ID of the pathway compiled from the agent’s version for this binding. Regenerated on every attach.
string
ID of the agent version the binding was compiled from: the newest version on the dev timeline. Versions saved on branches are ignored.
string[]
The numbers that were attached, after trimming.
null | array
null on success, or a list of error objects if the request failed. Returns 404 NOT_FOUND for an unknown agent, 400 NO_VERSIONS when the agent has no saved versions, and 422 COMPILE_FAILED when the newest version cannot be compiled.{
"data": {
"agent_id": "56ad3ffc-41c3-4466-b41f-220d17779a74",
"persona_id": "4cbdee81-f067-4fb7-8738-0995316ab3ce",
"pathway_id": "48e86cb8-4d1a-4be6-a85a-4c277255eeb4",
"compiled_from_version": "4adbe770-fc45-42ea-aa17-7533429c34f3",
"attached": [
"+18005551234",
"+18005556789"
]
},
"errors": null
}
{
"data": null,
"errors": [
{
"error": "INVALID_INBOUND_NUMBERS",
"message": "Some phone numbers were not found or do not belong to you"
}
]
}
{
"data": null,
"errors": [
{
"error": "INVALID_BODY",
"message": "inbound_numbers must be a non-empty array of phone numbers"
}
]
}
{
"data": null,
"errors": [
{
"error": "NO_VERSIONS",
"message": "Agent has no saved versions — save it in the builder first"
}
]
}
{
"data": null,
"errors": [
{
"error": "NOT_FOUND",
"message": "Agent not found"
}
]
}
Docs for agents: llms.txt
Was this page helpful?