Phone numbers

Buy a number

Buys the number on the customer’s own carrier account, points it at the trunk, and registers it, with inbound_agent_id answering it. The carrier charges that account at its own price; Wixzel Voice sells no numbers and adds nothing. Confirm the number and the price with the person before calling this.

Where the number needs regulatory approval, an approved bundle, compliance application or requirement group already on the carrier account is attached automatically. Without one the carrier refuses, and the error says where to get it.

Requires phone_numbers:purchase, which AI clients do not get unless the person ticks it, and an Idempotency-Key header: retrying with the same key returns the first result instead of buying twice. A number that was bought but could not be pointed at us answers 502 bought_not_connected; it stays on the carrier account and can be registered again.

POST

phone-numbers

purchase

Buy a number

curl --request POST \
  --url https://api.voice.wixzel.com/v1/phone-numbers/purchase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "sip_trunk_id": "6a96a3ead6e886d42462dd3e",
  "phone_number": "+14155550100",
  "country": "IN",
  "name": "<string>",
  "inbound_agent_id": "6a96a3ead6e886d42462dd3e"
}
'

import requests

url = "https://api.voice.wixzel.com/v1/phone-numbers/purchase"

payload = {
    "sip_trunk_id": "6a96a3ead6e886d42462dd3e",
    "phone_number": "+14155550100",
    "country": "IN",
    "name": "<string>",
    "inbound_agent_id": "6a96a3ead6e886d42462dd3e"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sip_trunk_id: '6a96a3ead6e886d42462dd3e',
    phone_number: '+14155550100',
    country: 'IN',
    name: '<string>',
    inbound_agent_id: '6a96a3ead6e886d42462dd3e'
  })
};

fetch('https://api.voice.wixzel.com/v1/phone-numbers/purchase', 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.voice.wixzel.com/v1/phone-numbers/purchase",
  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([
    'sip_trunk_id' => '6a96a3ead6e886d42462dd3e',
    'phone_number' => '+14155550100',
    'country' => 'IN',
    'name' => '<string>',
    'inbound_agent_id' => '6a96a3ead6e886d42462dd3e'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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.voice.wixzel.com/v1/phone-numbers/purchase"

	payload := strings.NewReader("{\n  \"sip_trunk_id\": \"6a96a3ead6e886d42462dd3e\",\n  \"phone_number\": \"+14155550100\",\n  \"country\": \"IN\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.voice.wixzel.com/v1/phone-numbers/purchase")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sip_trunk_id\": \"6a96a3ead6e886d42462dd3e\",\n  \"phone_number\": \"+14155550100\",\n  \"country\": \"IN\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.voice.wixzel.com/v1/phone-numbers/purchase")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sip_trunk_id\": \"6a96a3ead6e886d42462dd3e\",\n  \"phone_number\": \"+14155550100\",\n  \"country\": \"IN\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}"

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

{
  "id": "6a96a3ead6e886d42462dd3e",
  "object": "phone_number",
  "phone_number": "<string>",
  "name": "<string>",
  "sip_trunk_id": "6a96a3ead6e886d42462dd3e",
  "inbound_agent_id": "6a96a3ead6e886d42462dd3e",
  "status": "<string>",
  "created_at": "2026-09-01T12:00:00.000Z",
  "purchase_status": "complete"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Your Wixzel Voice API key: Authorization: Bearer wv_live_.... Keys are scoped; grant only what the integration needs.

Headers

Idempotency-Key

string

required

A unique value per purchase attempt, e.g. a UUID.

Required string length: 1 - 255

Body

application/json

sip_trunk_id

string

required

A trunk made by connecting a carrier account. The number is bought on that account.

Pattern: ^[0-9a-f]{24}$

Example:

"6a96a3ead6e886d42462dd3e"

phone_number

string

required

Pattern: ^\+[1-9]\d{6,14}$

Example:

"+14155550100"

country

string

required

The country you searched in.

Pattern: ^[A-Z]{2}$

Example:

"IN"

type

enum<string>

required

The type you searched for. Used to find the approved regulatory documents it needs.

Available options:

local,

mobile,

toll_free

name

string

Maximum string length: 200

inbound_agent_id

string

Answers inbound calls to the number. It also becomes the agent’s caller id if the agent has none.

Pattern: ^[0-9a-f]{24}$

Example:

"6a96a3ead6e886d42462dd3e"

Response

The number, bought and registered

string

required

Pattern: ^[0-9a-f]{24}$

Example:

"6a96a3ead6e886d42462dd3e"

object

enum<string>

required

Available options:

phone_number

phone_number

string

required

name

string | null

required

sip_trunk_id

string | null

required

Pattern: ^[0-9a-f]{24}$

Example:

"6a96a3ead6e886d42462dd3e"

inbound_agent_id

string | null

required

Pattern: ^[0-9a-f]{24}$

Example:

"6a96a3ead6e886d42462dd3e"

status

string

required

created_at

string<date-time>

required

ISO 8601, always UTC.

Example:

"2026-09-01T12:00:00.000Z"

purchase_status

enum<string>

required

pending when the carrier took the order and is still processing it, which can take a few minutes for numbers that need regulatory review. The number is registered either way.

Available options:

complete,

pending

Buy a number

curl --request POST \
  --url https://api.voice.wixzel.com/v1/phone-numbers/purchase \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "sip_trunk_id": "6a96a3ead6e886d42462dd3e",
  "phone_number": "+14155550100",
  "country": "IN",
  "name": "<string>",
  "inbound_agent_id": "6a96a3ead6e886d42462dd3e"
}
'

import requests

url = "https://api.voice.wixzel.com/v1/phone-numbers/purchase"

payload = {
    "sip_trunk_id": "6a96a3ead6e886d42462dd3e",
    "phone_number": "+14155550100",
    "country": "IN",
    "name": "<string>",
    "inbound_agent_id": "6a96a3ead6e886d42462dd3e"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sip_trunk_id: '6a96a3ead6e886d42462dd3e',
    phone_number: '+14155550100',
    country: 'IN',
    name: '<string>',
    inbound_agent_id: '6a96a3ead6e886d42462dd3e'
  })
};

fetch('https://api.voice.wixzel.com/v1/phone-numbers/purchase', 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.voice.wixzel.com/v1/phone-numbers/purchase",
  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([
    'sip_trunk_id' => '6a96a3ead6e886d42462dd3e',
    'phone_number' => '+14155550100',
    'country' => 'IN',
    'name' => '<string>',
    'inbound_agent_id' => '6a96a3ead6e886d42462dd3e'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$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.voice.wixzel.com/v1/phone-numbers/purchase"

	payload := strings.NewReader("{\n  \"sip_trunk_id\": \"6a96a3ead6e886d42462dd3e\",\n  \"phone_number\": \"+14155550100\",\n  \"country\": \"IN\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}")

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

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	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.voice.wixzel.com/v1/phone-numbers/purchase")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sip_trunk_id\": \"6a96a3ead6e886d42462dd3e\",\n  \"phone_number\": \"+14155550100\",\n  \"country\": \"IN\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.voice.wixzel.com/v1/phone-numbers/purchase")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sip_trunk_id\": \"6a96a3ead6e886d42462dd3e\",\n  \"phone_number\": \"+14155550100\",\n  \"country\": \"IN\",\n  \"name\": \"<string>\",\n  \"inbound_agent_id\": \"6a96a3ead6e886d42462dd3e\"\n}"

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

{
  "id": "6a96a3ead6e886d42462dd3e",
  "object": "phone_number",
  "phone_number": "<string>",
  "name": "<string>",
  "sip_trunk_id": "6a96a3ead6e886d42462dd3e",
  "inbound_agent_id": "6a96a3ead6e886d42462dd3e",
  "status": "<string>",
  "created_at": "2026-09-01T12:00:00.000Z",
  "purchase_status": "complete"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "agent_not_found",
    "message": "<string>",
    "request_id": "req_01HXYZ...",
    "param": "<string>",
    "doc_url": "<string>"
  }
}

Getting started

Guides

Carriers

Concepts

API reference

Buy a number

Authorizations

Headers

Body

Response