SIP Integration

​

Overview

• Creating SIP trunks via the Setup Wizard or API
• Attaching numbers and DIDs for inbound and outbound routing
• Auto-discovery of endpoint settings, connection tests, and live SIP tracing
• Number porting to bring existing numbers to Bland
• Connection endpoints, firewall allow-listing, and security requirements
• The full SIP API reference

​

Quick Start

curl -X POST https://api.bland.ai/v1/calls \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Say hi to the nice person!",
    "from": "+12341234123",
    "phone_number": "<the callee phone number>"
  }'

​

SIP Setup Wizard

​

Step 1: Setup

curl -X POST https://api.bland.ai/v1/sip/trunks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Production",
    "provider": "Asterisk",
    "direction": "both"
  }'

​

Step 2: Provider

• Vonage — SIP endpoint
• Asterisk / FreePBX — Public IP or hostname
• 3CX — SIP trunk FQDN
• Cisco UCM / CUBE — Gateway address
• RingCentral — SIP endpoint
• Microsoft Teams — Requires a certified SBC (direct connection not supported)
• Other — Any standard SIP endpoint

curl -X POST https://api.bland.ai/v1/sip/parse-destination \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "input": "sip:your.provider.com:5061;transport=tls" }'

​

Step 3: Discovery

1. Resolves DNS — A/AAAA and SRV records (_sip._udp, _sip._tcp, _sips._tcp)
2. Probes SIP ports — Tests common ports over UDP, TCP, and TLS with SIP OPTIONS messages
3. Analyzes responses — Detects your PBX system (Asterisk, FreeSWITCH, Kamailio, 3CX, Cisco, etc.), supported codecs, and methods

curl -X POST https://api.bland.ai/v1/sip/discover \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "host": "sip.example.com" }'

​

Step 4: Firewall

curl -X GET https://api.bland.ai/v1/sip/firewall-ips \
  -H "Authorization: Bearer <token>"

​

Step 5: Authentication

• IP-based (recommended) — Bland’s signaling IPs are allow-listed on your server, and Bland trusts your endpoint by source IP. No credentials to manage.
• Registration-based — Bland registers with your server using a username and password via SIP REGISTER. A derived password is returned that you configure in your PBX.

{
  "type": "inbound",
  "auth_mode": "register",
  "register_auth": {
    "username": "my-trunk",
    "password": "a-strong-password"
  }
}

​

Step 6: Complete

curl -X GET 'https://api.bland.ai/v1/sip/status?phone_number=%2B14155550100' \
  -H "Authorization: Bearer <token>"

​

Trunks, Numbers, and DIDs

​

Attach numbers and DIDs

• PSTN numbers are normalized to E.164 (e.g. +14155550100).
• DIDs and extensions — when a number is bound to a trunk (trunk_id), non-E.164 SIP identities such as DIDs and dial-plan extensions (e.g. 2001) are accepted and stored as-is.
• Each number can carry an inbound and an outbound configuration independently.

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

​

Inbound numbers

​

Inspect a call (SIP trace)

​

Advanced configuration

• Failover — primary, secondary, and tertiary SIP servers with automatic failover triggers (unreachable, auth failure, timeout) and failback mode (auto/manual).
• Codecs — reorder and enable/disable codecs (PCMU, PCMA, Opus, G.722, G.729) with optional transcoding.
• Alerts — thresholds for unreachable duration, failure rate, and response time, with email, SMS, and webhook channels.

​

Number Porting

​

How Number Porting Works

​

Porting via the Dashboard

curl -X GET 'https://api.bland.ai/v1/sip/port/check?phone_numbers[]=%2B14150000000' \
  -H "Authorization: Bearer <token>"

• Authorized representative — Name and email of the person authorized to port the numbers
• Service address — The address on file with the losing carrier (must match their records)
• Target port date — Earliest date for the port (minimum 7 days from today)
• Proof of ownership — Upload a utility bill or carrier invoice (PDF or image, max 10MB) showing the account name and service address

curl -X POST https://api.bland.ai/v1/sip/port/document \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/utility-bill.pdf"

curl -X POST https://api.bland.ai/v1/sip/port/initiate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+14150000000"],
    "losing_carrier_information": {
      "customer_type": "Business",
      "customer_name": "Acme Corp",
      "account_number": "ACC-12345",
      "account_telephone_number": "+14150000000",
      "authorized_representative": "Jane Doe",
      "authorized_representative_email": "jane@acme.com",
      "address": {
        "street": "123 Main St",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94105",
        "country": "US"
      }
    },
    "target_port_in_date": "2026-03-20",
    "documents": ["doc_abc123"]
  }'

​

Connection Endpoints

• Signaling (connection): SIP runs exclusively over TLS on TCP port 5061 — there is no plaintext UDP/5060 listener. Each region has two signaling IPs (one per availability zone) behind its FQDN for high availability; send SIP to the FQDN and it balances across both.
• Media (RTP): Audio is carried over SRTP on a separate set of media IPs per region, over UDP ports 16384–32768.

​

Firewall allow-list

​

Requirements and Security

• SIP signaling: TLS 1.2 or higher, TCP port 5061 only. UDP and plaintext 5060 are not accepted.
• Ensure the Let’s Encrypt ISRG Root X1 CA is installed — downloadable here.

• SRTP using AES_CM_128_HMAC_SHA1_80.
• RTP over UDP ports 16384–32768; RTCP uses RTP port + 1.

• PCMU (G.711 μ-law), PCMA (G.711 A-law), Opus, G.722
• G.729 available via advanced configuration

• Methods: INVITE, ACK, BYE, CANCEL, OPTIONS, REFER
• DTMF: RFC 2833 (out-of-band via RTP telephone-event)
• Number format: E.164 for PSTN; DIDs and extensions supported on trunk-bound numbers
• Authentication: IP-based (default) or SIP REGISTER digest auth

​

Entitlement Requirement

​

API Reference

​

Trunk Management

​

Numbers & Configuration

​

Discovery & Testing

​

Monitoring

​

Number Porting

​

Notes

• A trunk lets you configure the connection once and attach many numbers and DIDs to it.
• Each number can have one inbound and one outbound configuration, attached independently.
• Up to 100 numbers can be attached in a single API call.
• Trunk-bound numbers accept non-E.164 DIDs and extensions in addition to E.164 PSTN numbers.
• All requests must conform to the expected schema; invalid payloads are rejected with a 400 response.
• Test calls are rate-limited to 10 per 15 minutes per organization.
• Number porting typically takes 7–14 business days. Track status via the dashboard or API.
• Health checks probe outbound endpoints via SIP OPTIONS. Inbound-only configurations show as “unchecked” since there is no outbound endpoint to probe.