Buy phone numbers API

POST

phone-numbers

buy

cURL

curl --request POST \
  --url https://api.bolna.ai/phone-numbers/buy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number": "+19876543210",
  "compliance_application_id": "a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f"
}
'

import requests

url = "https://api.bolna.ai/phone-numbers/buy"

payload = {
    "phone_number": "+19876543210",
    "compliance_application_id": "a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    phone_number: '+19876543210',
    compliance_application_id: 'a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f'
  })
};

fetch('https://api.bolna.ai/phone-numbers/buy', 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.bolna.ai/phone-numbers/buy",
  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_number' => '+19876543210',
    'compliance_application_id' => 'a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.bolna.ai/phone-numbers/buy"

	payload := strings.NewReader("{\n  \"phone_number\": \"+19876543210\",\n  \"compliance_application_id\": \"a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.bolna.ai/phone-numbers/buy")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"+19876543210\",\n  \"compliance_application_id\": \"a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bolna.ai/phone-numbers/buy")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number\": \"+19876543210\",\n  \"compliance_application_id\": \"a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f\"\n}"

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

{
  "id": "133b9a7d-59b1-49c4-b62a-c4924503e38b",
  "agent_id": null,
  "bolna_owned": true,
  "deleted": false,
  "renewal": true,
  "payment_uuid": "de36c363-6a2d-4e83-ba5b-fbb8d0ac8c32",
  "phone_number": "+19876543210",
  "price": 500,
  "telephony_provider": "twilio",
  "telephony_sid": "19876543210",
  "created_at": "2025-07-27T20:51:49.468787",
  "updated_at": "2025-07-27T20:51:49.468796"
}

{
  "error": 123,
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Purchase a phone number

country

enum<string>

required

The country code for the phone number.

Available options:

US,

IN

phone_number

string

required

E.164 formatted phone number, including country code.

Pattern: ^\+[1-9][0-9]{7,14}$

Example:

"+19876543210"

provider

enum<string>

The telephony provider for the phone number.

Available options:

twilio,

plivo,

vobiz

compliance_application_id

string<uuid>

Optional ID of the approved compliance application under which the phone number should be purchased. Useful when your account has multiple approved compliance applications. Get the IDs from the list compliance applications API.

Example:

"a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f"

Response

Sub-account create response

string<uuid>

Unique identifier for the purchased phone number record.

Example:

"133b9a7d-59b1-49c4-b62a-c4924503e38b"

agent_id

string<uuid> | null

Identifier of the agent associated with the number, if applicable.

Example:

null

bolna_owned

boolean

Indicates if the number is owned by Bolna.

Example:

true

deleted

boolean

Indicates whether the number record is deleted.

Example:

false

renewal

boolean

Indicates if the phone number subscription will auto-renew.

Example:

true

payment_uuid

string<uuid>

Unique identifier for the payment transaction.

Example:

"de36c363-6a2d-4e83-ba5b-fbb8d0ac8c32"

phone_number

string

E.164 formatted purchased phone number.

Pattern: ^\+[1-9][0-9]{7,14}$

Example:

"+19876543210"

price

number<float>

Price for the phone number in cents.

Example:

500

telephony_provider

enum<string>

Name of the telephony provider for the number.

Available options:

twilio,

plivo,

vonage,

telnyx

telephony_sid

string

Unique identifier or SID for the phone number within the telephony provider.

Example:

"19876543210"

created_at

string<date-time>

Timestamp when the record was created.

Example:

"2025-07-27T20:51:49.468787"

updated_at

string<date-time>

Timestamp when the record was last updated.

Example:

"2025-07-27T20:51:49.468796"

cURL

curl --request POST \
  --url https://api.bolna.ai/phone-numbers/buy \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone_number": "+19876543210",
  "compliance_application_id": "a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f"
}
'

import requests

url = "https://api.bolna.ai/phone-numbers/buy"

payload = {
    "phone_number": "+19876543210",
    "compliance_application_id": "a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    phone_number: '+19876543210',
    compliance_application_id: 'a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f'
  })
};

fetch('https://api.bolna.ai/phone-numbers/buy', 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.bolna.ai/phone-numbers/buy",
  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_number' => '+19876543210',
    'compliance_application_id' => 'a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.bolna.ai/phone-numbers/buy"

	payload := strings.NewReader("{\n  \"phone_number\": \"+19876543210\",\n  \"compliance_application_id\": \"a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	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.bolna.ai/phone-numbers/buy")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"+19876543210\",\n  \"compliance_application_id\": \"a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bolna.ai/phone-numbers/buy")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number\": \"+19876543210\",\n  \"compliance_application_id\": \"a3f1c2d4-5e6b-4c7d-8e9f-0a1b2c3d4e5f\"\n}"

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

{
  "id": "133b9a7d-59b1-49c4-b62a-c4924503e38b",
  "agent_id": null,
  "bolna_owned": true,
  "deleted": false,
  "renewal": true,
  "payment_uuid": "de36c363-6a2d-4e83-ba5b-fbb8d0ac8c32",
  "phone_number": "+19876543210",
  "price": 500,
  "telephony_provider": "twilio",
  "telephony_sid": "19876543210",
  "created_at": "2025-07-27T20:51:49.468787",
  "updated_at": "2025-07-27T20:51:49.468796"
}

{
  "error": 123,
  "message": "<string>"
}

Get started

Voice agents

Telephony

Workflows

Account

Legacy

Buy phone numbers API

Authorizations

Body

Response