Skip to main content
POST
/
v1
/
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": {}
}
'
{
  "data": {
    "configured": ["+14150000001", "+14150000002", "+14150000003"],
    "failed": []
  },
  "errors": null
}

​
Headers

​
authorization
string
required
Your API key for authentication.

​
Body

​
phone_number
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.
​
phone_numbers
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.
​
directions
array
required
An array of direction objects. Each specifies either inbound or outbound routing configuration.
​
service
string
required
Must be set to "sip".
​
trunk_id
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

​
directions[].type
string
required
Set to "inbound".
​
directions[].auth_mode
string
Authentication mode: "ip" (default) or "register". When set to "register", you must also provide register_auth.
​
directions[].register_auth
object
Required when auth_mode is "register". Contains username (string) and password (string, min 8 characters).
​
directions[].sip_endpoint
string
Your SIP server address for inbound call forwarding (optional). Format: sip:host or host.
​
directions[].headers
object
Custom SIP header mappings. See header configuration examples below.
​
directions[].options
object
Connection options: port (number), transport ("udp", "tcp", or "tls"), secure_media (boolean), sip_username (string), sip_password (string).

​
Outbound Direction Object

​
directions[].type
string
required
Set to "outbound".
​
directions[].sip_endpoint
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.
​
directions[].headers
object
Custom SIP header mappings.
​
directions[].options
object
Connection options: port (number), transport ("udp", "tcp", or "tls"), secure_media (boolean), sip_username (string), sip_password (string).

​
Response

​
configured
array
Array of successfully configured phone numbers.
​
failed
array
Array of phone numbers that failed to configure, with error reasons.
​
register_password_for_pbx
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