Attach SIP Configuration

Attach SIP configuration to one or more phone numbers for inbound and/or outbound routing.

POST /v1/sip/attach

Attach SIP Configuration

cURL

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": {}
}
'

Response

{
  "data": {
    "configured": ["[phone]", "[phone]", "[phone]"],
    "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., [phone]); 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": "[phone]",
    "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": ["[phone]", "[phone]", "[phone]"],
    "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": ["[phone]", "2001"],
    "directions": [{ "type": "inbound" }, { "type": "outbound" }],
    "service": "sip",
    "trunk_id": "<trunk-id>"
  }'

Response

{
  "data": {
    "configured": ["[phone]", "[phone]", "[phone]"],
    "failed": []
  },
  "errors": null
}

---

Docs for agents: llms.txt