Attach SIP Configuration

curl --request POST \
  --url https://api.bland.ai/v1/sip/attach \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "phone_number": "<string>",
  "phone_numbers": [
    "<string>"
  ],
  "directions": [
    {}
  ],
  "service": "<string>",
  "trunk_id": "<string>",
  "directions[].type": "<string>",
  "directions[].auth_mode": "<string>",
  "directions[].register_auth": {},
  "directions[].sip_endpoint": "<string>",
  "directions[].headers": {},
  "directions[].options": {}
}
'

import requests

url = "https://api.bland.ai/v1/sip/attach"

payload = {
    "phone_number": "<string>",
    "phone_numbers": ["<string>"],
    "directions": [{}],
    "service": "<string>",
    "trunk_id": "<string>",
    "directions[].type": "<string>",
    "directions[].auth_mode": "<string>",
    "directions[].register_auth": {},
    "directions[].sip_endpoint": "<string>",
    "directions[].headers": {},
    "directions[].options": {}
}
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({
    phone_number: '<string>',
    phone_numbers: ['<string>'],
    directions: [{}],
    service: '<string>',
    trunk_id: '<string>',
    'directions[].type': '<string>',
    'directions[].auth_mode': '<string>',
    'directions[].register_auth': {},
    'directions[].sip_endpoint': '<string>',
    'directions[].headers': {},
    'directions[].options': {}
  })
};

fetch('https://api.bland.ai/v1/sip/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/v1/sip/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([
    'phone_number' => '<string>',
    'phone_numbers' => [
        '<string>'
    ],
    'directions' => [
        [
                
        ]
    ],
    'service' => '<string>',
    'trunk_id' => '<string>',
    'directions[].type' => '<string>',
    'directions[].auth_mode' => '<string>',
    'directions[].register_auth' => [
        
    ],
    'directions[].sip_endpoint' => '<string>',
    'directions[].headers' => [
        
    ],
    'directions[].options' => [
        
    ]
  ]),
  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/v1/sip/attach"

	payload := strings.NewReader("{\n  \"phone_number\": \"<string>\",\n  \"phone_numbers\": [\n    \"<string>\"\n  ],\n  \"directions\": [\n    {}\n  ],\n  \"service\": \"<string>\",\n  \"trunk_id\": \"<string>\",\n  \"directions[].type\": \"<string>\",\n  \"directions[].auth_mode\": \"<string>\",\n  \"directions[].register_auth\": {},\n  \"directions[].sip_endpoint\": \"<string>\",\n  \"directions[].headers\": {},\n  \"directions[].options\": {}\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/v1/sip/attach")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"<string>\",\n  \"phone_numbers\": [\n    \"<string>\"\n  ],\n  \"directions\": [\n    {}\n  ],\n  \"service\": \"<string>\",\n  \"trunk_id\": \"<string>\",\n  \"directions[].type\": \"<string>\",\n  \"directions[].auth_mode\": \"<string>\",\n  \"directions[].register_auth\": {},\n  \"directions[].sip_endpoint\": \"<string>\",\n  \"directions[].headers\": {},\n  \"directions[].options\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/sip/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  \"phone_number\": \"<string>\",\n  \"phone_numbers\": [\n    \"<string>\"\n  ],\n  \"directions\": [\n    {}\n  ],\n  \"service\": \"<string>\",\n  \"trunk_id\": \"<string>\",\n  \"directions[].type\": \"<string>\",\n  \"directions[].auth_mode\": \"<string>\",\n  \"directions[].register_auth\": {},\n  \"directions[].sip_endpoint\": \"<string>\",\n  \"directions[].headers\": {},\n  \"directions[].options\": {}\n}"

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

{
  "data": {
    "configured": ["+14150000001", "+14150000002", "+14150000003"],
    "failed": []
  },
  "errors": null
}

POST

sip

attach

Attach SIP Configuration

curl --request POST \
  --url https://api.bland.ai/v1/sip/attach \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "phone_number": "<string>",
  "phone_numbers": [
    "<string>"
  ],
  "directions": [
    {}
  ],
  "service": "<string>",
  "trunk_id": "<string>",
  "directions[].type": "<string>",
  "directions[].auth_mode": "<string>",
  "directions[].register_auth": {},
  "directions[].sip_endpoint": "<string>",
  "directions[].headers": {},
  "directions[].options": {}
}
'

import requests

url = "https://api.bland.ai/v1/sip/attach"

payload = {
    "phone_number": "<string>",
    "phone_numbers": ["<string>"],
    "directions": [{}],
    "service": "<string>",
    "trunk_id": "<string>",
    "directions[].type": "<string>",
    "directions[].auth_mode": "<string>",
    "directions[].register_auth": {},
    "directions[].sip_endpoint": "<string>",
    "directions[].headers": {},
    "directions[].options": {}
}
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({
    phone_number: '<string>',
    phone_numbers: ['<string>'],
    directions: [{}],
    service: '<string>',
    trunk_id: '<string>',
    'directions[].type': '<string>',
    'directions[].auth_mode': '<string>',
    'directions[].register_auth': {},
    'directions[].sip_endpoint': '<string>',
    'directions[].headers': {},
    'directions[].options': {}
  })
};

fetch('https://api.bland.ai/v1/sip/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/v1/sip/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([
    'phone_number' => '<string>',
    'phone_numbers' => [
        '<string>'
    ],
    'directions' => [
        [
                
        ]
    ],
    'service' => '<string>',
    'trunk_id' => '<string>',
    'directions[].type' => '<string>',
    'directions[].auth_mode' => '<string>',
    'directions[].register_auth' => [
        
    ],
    'directions[].sip_endpoint' => '<string>',
    'directions[].headers' => [
        
    ],
    'directions[].options' => [
        
    ]
  ]),
  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/v1/sip/attach"

	payload := strings.NewReader("{\n  \"phone_number\": \"<string>\",\n  \"phone_numbers\": [\n    \"<string>\"\n  ],\n  \"directions\": [\n    {}\n  ],\n  \"service\": \"<string>\",\n  \"trunk_id\": \"<string>\",\n  \"directions[].type\": \"<string>\",\n  \"directions[].auth_mode\": \"<string>\",\n  \"directions[].register_auth\": {},\n  \"directions[].sip_endpoint\": \"<string>\",\n  \"directions[].headers\": {},\n  \"directions[].options\": {}\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/v1/sip/attach")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"<string>\",\n  \"phone_numbers\": [\n    \"<string>\"\n  ],\n  \"directions\": [\n    {}\n  ],\n  \"service\": \"<string>\",\n  \"trunk_id\": \"<string>\",\n  \"directions[].type\": \"<string>\",\n  \"directions[].auth_mode\": \"<string>\",\n  \"directions[].register_auth\": {},\n  \"directions[].sip_endpoint\": \"<string>\",\n  \"directions[].headers\": {},\n  \"directions[].options\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/sip/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  \"phone_number\": \"<string>\",\n  \"phone_numbers\": [\n    \"<string>\"\n  ],\n  \"directions\": [\n    {}\n  ],\n  \"service\": \"<string>\",\n  \"trunk_id\": \"<string>\",\n  \"directions[].type\": \"<string>\",\n  \"directions[].auth_mode\": \"<string>\",\n  \"directions[].register_auth\": {},\n  \"directions[].sip_endpoint\": \"<string>\",\n  \"directions[].headers\": {},\n  \"directions[].options\": {}\n}"

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

{
  "data": {
    "configured": ["+14150000001", "+14150000002", "+14150000003"],
    "failed": []
  },
  "errors": null
}

Headers

string

required

Your API key for authentication.

Body

string

A single phone number to configure. PSTN numbers are normalized to E.164 (e.g., +14150000000); when bound to a trunk (trunk_id), non-E.164 SIP identities such as DIDs and extensions are also accepted. Use either phone_number or phone_numbers, not both.

string[]

An array of phone numbers or DIDs to configure (up to 100). PSTN numbers are normalized to E.164; trunk-bound numbers also accept DIDs and extensions. Use either phone_number or phone_numbers, not both.

array

required

An array of direction objects. Each specifies either inbound or outbound routing configuration.

string

required

Must be set to "sip".

string

Bind the numbers to a reusable trunk. When set, outbound endpoint and authentication are inherited from the trunk (no need to repeat sip_endpoint/auth per number), and non-E.164 DIDs and extensions are accepted.

Inbound Direction Object

string

required

Set to "inbound".

string

Authentication mode: "ip" (default) or "register". When set to "register", you must also provide register_auth.

object

Required when auth_mode is "register". Contains username (string) and password (string, min 8 characters).

string

Your SIP server address for inbound call forwarding (optional). Format: sip:host or host.

object

Custom SIP header mappings. See header configuration examples below.

object

Connection options: port (number), transport ("udp", "tcp", or "tls"), secure_media (boolean), sip_username (string), sip_password (string).

Outbound Direction Object

string

required

Set to "outbound".

string

required

Your SIP provider’s endpoint, as a valid SIP URI (e.g., sip:your.provider.com). Required for outbound unless the numbers are bound to a trunk_id, in which case it is inherited from the trunk.

object

Custom SIP header mappings.

object

Connection options: port (number), transport ("udp", "tcp", or "tls"), secure_media (boolean), sip_username (string), sip_password (string).

Response

array

Array of successfully configured phone numbers.

array

Array of phone numbers that failed to configure, with error reasons.

string

Only returned when using registration-based auth. This is the derived password you must configure in your PBX.

Header Configuration Examples

Headers allow you to map SIP headers to Bland pathway variables and vice versa.

Example Request (Outbound with Headers)

curl -X POST https://api.bland.ai/v1/sip/attach \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14150000000",
    "directions": [
      {
        "type": "inbound",
        "headers": {
          "direction": "inbound",
          "headers": [
            { "type": "custom", "key": "X-Cool-Guy", "value": "First_Name" },
            { "type": "custom", "key": "Account_Type", "value": "VIP", "passthrough": true },
            { "type": "uui", "target": "CustomerId", "purpose": "bland", "encoding": "hex", "content": "id" }
          ]
        }
      },
      {
        "type": "outbound",
        "sip_endpoint": "sip:your.provider.com",
        "options": {
          "port": 5061,
          "transport": "tls",
          "secure_media": true,
          "sip_username": "bland",
          "sip_password": "password"
        },
        "headers": {
          "direction": "outbound",
          "headers": [
            { "type": "custom", "key": "Favorite_Color", "value": "X-Favorite-Color" },
            { "type": "custom", "key": "x-custom-id", "value": "12345", "passthrough": true },
            { "type": "uui", "target": "CustomerKV", "purpose": "bland", "content": "customerid_1234", "encoding": "hex" }
          ]
        }
      }
    ],
    "service": "sip"
  }'

Example Request (Batch Attach)

curl -X POST https://api.bland.ai/v1/sip/attach \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+14150000001", "+14150000002", "+14150000003"],
    "directions": [
      {
        "type": "outbound",
        "sip_endpoint": "sip:trunk.provider.com",
        "options": {
          "transport": "tls",
          "secure_media": true
        }
      }
    ],
    "service": "sip"
  }'

Example Request (Bind to a Trunk)

curl -X POST https://api.bland.ai/v1/sip/attach \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+14155550100", "2001"],
    "directions": [{ "type": "inbound" }, { "type": "outbound" }],
    "service": "sip",
    "trunk_id": "<trunk-id>"
  }'

{
  "data": {
    "configured": ["+14150000001", "+14150000002", "+14150000003"],
    "failed": []
  },
  "errors": null
}

Docs for agents: llms.txt

List SIP Numbers Update SIP Direction

⌘I

Basic Tutorials

Calls

Voices & Text to Speech

Conversational Pathways

Knowledge Bases

Numbers

Blocked Numbers

Widgets

Tools

Contacts

Memory

Node tests

Agent Testing

Evals

Guard Rails

Web Agents

Live Translation

Custom Twilio Accounts

Batches

Prompts

Account

Organizations

Messaging

SIP Trunks

Custom Dialing Pools

Personas

Citation Schemas

Alarms

Triage

Attach SIP Configuration

Headers

Body

Inbound Direction Object

Outbound Direction Object

Response

Header Configuration Examples

​Headers

​Body

​Inbound Direction Object

​Outbound Direction Object

​Response

​Header Configuration Examples

Headers

Body

Inbound Direction Object

Outbound Direction Object

Response

Header Configuration Examples