> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach SIP Configuration

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

### 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.

On an inbound mapping, set `"external_id": true` on one `custom` entry to store that header's value as the call's `external_id`. The header is still mapped into its variable as usual. You can then find the call with [`GET /v1/calls?external_id=`](https://docs.bland.ai/api-v1/get/calls) or [`GET /v1/calls/{external_id}`](https://docs.bland.ai/api-v1/get/calls-id). In the dashboard, select **External ID** on the inbound header row.

```json theme={null}
{ "type": "custom", "key": "X-Session-Id", "value": "session_id", "external_id": true }
```

```json Example Request (Outbound with Headers) theme={null}
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"
  }'
```

```json Example Request (Batch Attach) theme={null}
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"
  }'
```

```json Example Request (Bind to a Trunk) theme={null}
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>"
  }'
```

```json Response theme={null}
{
  "data": {
    "configured": ["+14150000001", "+14150000002", "+14150000003"],
    "failed": []
  },
  "errors": null
}
```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.