Initiate Port Request

POST

sip

port

initiate

curl --request POST \
  --url https://api.bland.ai/v1/sip/port/initiate \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "phone_numbers": [
    {}
  ],
  "losing_carrier_information": {},
  "target_port_in_date": "<string>",
  "documents": [
    {}
  ],
  "phone_number_pins": {},
  "notification_emails": [
    {}
  ]
}
'

import requests

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

payload = {
    "phone_numbers": [{}],
    "losing_carrier_information": {},
    "target_port_in_date": "<string>",
    "documents": [{}],
    "phone_number_pins": {},
    "notification_emails": [{}]
}
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_numbers: [{}],
    losing_carrier_information: {},
    target_port_in_date: '<string>',
    documents: [{}],
    phone_number_pins: {},
    notification_emails: [{}]
  })
};

fetch('https://api.bland.ai/v1/sip/port/initiate', 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/port/initiate",
  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_numbers' => [
        [
                
        ]
    ],
    'losing_carrier_information' => [
        
    ],
    'target_port_in_date' => '<string>',
    'documents' => [
        [
                
        ]
    ],
    'phone_number_pins' => [
        
    ],
    'notification_emails' => [
        [
                
        ]
    ]
  ]),
  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/port/initiate"

	payload := strings.NewReader("{\n  \"phone_numbers\": [\n    {}\n  ],\n  \"losing_carrier_information\": {},\n  \"target_port_in_date\": \"<string>\",\n  \"documents\": [\n    {}\n  ],\n  \"phone_number_pins\": {},\n  \"notification_emails\": [\n    {}\n  ]\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/port/initiate")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_numbers\": [\n    {}\n  ],\n  \"losing_carrier_information\": {},\n  \"target_port_in_date\": \"<string>\",\n  \"documents\": [\n    {}\n  ],\n  \"phone_number_pins\": {},\n  \"notification_emails\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/sip/port/initiate")

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_numbers\": [\n    {}\n  ],\n  \"losing_carrier_information\": {},\n  \"target_port_in_date\": \"<string>\",\n  \"documents\": [\n    {}\n  ],\n  \"phone_number_pins\": {},\n  \"notification_emails\": [\n    {}\n  ]\n}"

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

{
  "data": {
    "port_request_id": "port_xyz789",
    "status": "waiting_for_signature",
    "signature_url": "https://sign.example.com/loa/port_xyz789",
    "phone_numbers": ["+14150000000", "+14150000001"]
  },
  "errors": null
}

Headers

string

required

Your API key for authentication.

Body

array

required

Array of phone numbers to port. Each must be in E.164 format. You should verify portability first using GET /v1/sip/port/check.

object

required

Information about the account with the current carrier. It must match the carrier’s records exactly.

customer_type (string, required): "Business" or "Individual". Values are case-sensitive.
customer_name (string, required): Name on the carrier account.
account_number (string): Account number with the losing carrier.
account_telephone_number (string, required): Billing telephone number on the carrier account.
authorized_representative (string, required): Full name of the person authorized to port the numbers.
authorized_representative_email (string, required): Email that receives the Letter of Authorization to sign.
address (object, required): Service address with street, street_2 (optional), city, state, zip, and country.

string

required

Requested port date in YYYY-MM-DD format. Must be at least 4 days from today.

array

required

Array of document SIDs returned from POST /v1/sip/port/document. At least one is required.

object

Map of phone number to its account PIN with the losing carrier, for example {"+14150000000": "1234"}. Required for numbers where the portability check returns pin_required.

array

Emails that receive port status updates. Defaults to authorized_representative_email.

Response

string

Unique identifier for the port request.

string

Initial status: "waiting_for_signature".

string

URL for electronically signing the Letter of Authorization.

array

Array of phone numbers included in the port request.

Number porting typically takes 7–14 business days. Track progress via GET /v1/sip/port or the SIP Dashboard. Port status flow: waiting_for_signature → submitted → in_progress → completed

Example Request

curl -X POST https://api.bland.ai/v1/sip/port/initiate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["+14150000000", "+14150000001"],
    "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",
        "street_2": "Suite 100",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94105",
        "country": "US"
      }
    },
    "target_port_in_date": "2026-03-20",
    "notification_emails": ["it@acme.com"],
    "documents": ["doc_abc123"]
  }'

{
  "data": {
    "port_request_id": "port_xyz789",
    "status": "waiting_for_signature",
    "signature_url": "https://sign.example.com/loa/port_xyz789",
    "phone_numbers": ["+14150000000", "+14150000001"]
  },
  "errors": null
}

Docs for agents: llms.txt

⌘I

Initiate Port Request

curl --request POST \
  --url https://api.bland.ai/v1/sip/port/initiate \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "phone_numbers": [
    {}
  ],
  "losing_carrier_information": {},
  "target_port_in_date": "<string>",
  "documents": [
    {}
  ],
  "phone_number_pins": {},
  "notification_emails": [
    {}
  ]
}
'

import requests

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

payload = {
    "phone_numbers": [{}],
    "losing_carrier_information": {},
    "target_port_in_date": "<string>",
    "documents": [{}],
    "phone_number_pins": {},
    "notification_emails": [{}]
}
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_numbers: [{}],
    losing_carrier_information: {},
    target_port_in_date: '<string>',
    documents: [{}],
    phone_number_pins: {},
    notification_emails: [{}]
  })
};

fetch('https://api.bland.ai/v1/sip/port/initiate', 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/port/initiate",
  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_numbers' => [
        [
                
        ]
    ],
    'losing_carrier_information' => [
        
    ],
    'target_port_in_date' => '<string>',
    'documents' => [
        [
                
        ]
    ],
    'phone_number_pins' => [
        
    ],
    'notification_emails' => [
        [
                
        ]
    ]
  ]),
  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/port/initiate"

	payload := strings.NewReader("{\n  \"phone_numbers\": [\n    {}\n  ],\n  \"losing_carrier_information\": {},\n  \"target_port_in_date\": \"<string>\",\n  \"documents\": [\n    {}\n  ],\n  \"phone_number_pins\": {},\n  \"notification_emails\": [\n    {}\n  ]\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/port/initiate")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_numbers\": [\n    {}\n  ],\n  \"losing_carrier_information\": {},\n  \"target_port_in_date\": \"<string>\",\n  \"documents\": [\n    {}\n  ],\n  \"phone_number_pins\": {},\n  \"notification_emails\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/sip/port/initiate")

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_numbers\": [\n    {}\n  ],\n  \"losing_carrier_information\": {},\n  \"target_port_in_date\": \"<string>\",\n  \"documents\": [\n    {}\n  ],\n  \"phone_number_pins\": {},\n  \"notification_emails\": [\n    {}\n  ]\n}"

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

{
  "data": {
    "port_request_id": "port_xyz789",
    "status": "waiting_for_signature",
    "signature_url": "https://sign.example.com/loa/port_xyz789",
    "phone_numbers": ["+14150000000", "+14150000001"]
  },
  "errors": null
}

Basic Tutorials

Agent Onboarding

Calls

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

Initiate Port Request

Headers

Body

Response

​Headers

​Body

​Response

Headers

Body

Response