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>"
],
"environment": "<string>"
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/inbound/attach"
payload = {
"inbound_numbers": ["<string>"],
"environment": "<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>'], environment: '<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>'
],
'environment' => '<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 \"environment\": \"<string>\"\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 \"environment\": \"<string>\"\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 \"environment\": \"<string>\"\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": "AGENT_ENV_UNPINNED",
"message": "Staging has no published version. Publish to staging first."
}
]
}
{
"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. Enterprise plans can pass environment: "staging" so calls run the version pinned to staging instead. 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.string
Which environment calls to these numbers run:
production or staging. When you omit it, a number already attached to this agent on staging stays on staging, and every other number answers on production. Pass production to move a staging number back. Any other value returns 400 INVALID_BODY.staging is enterprise only and applies to calls. Texts to a staging number still run the production version. Every check below runs before anything is written:403 ENTERPRISE_REQUIREDif your organization is not on an enterprise plan.409 STAGING_NUMBER_UNSUPPORTEDif your account or any of the numbers runs on dedicated infrastructure.409 AGENT_ENV_UNPINNEDif nothing is published to staging.409 AGENT_VARIABLE_UNRESOLVEDif a variable the staging version references has no staging value, or409 AGENT_SNAPSHOT_INVALIDif the staging version can’t run.
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": "AGENT_ENV_UNPINNED",
"message": "Staging has no published version. Publish to staging first."
}
]
}
{
"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?
⌘I
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>"
],
"environment": "<string>"
}
'import requests
url = "https://api.bland.ai/v2/agents/{agent_id}/inbound/attach"
payload = {
"inbound_numbers": ["<string>"],
"environment": "<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>'], environment: '<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>'
],
'environment' => '<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 \"environment\": \"<string>\"\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 \"environment\": \"<string>\"\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 \"environment\": \"<string>\"\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": "AGENT_ENV_UNPINNED",
"message": "Staging has no published version. Publish to staging first."
}
]
}
{
"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"
}
]
}