List Phone Numbers

curl --request GET \
  --url https://api.callhq.ai/api/phone-numbers \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.callhq.ai/api/phone-numbers', 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.callhq.ai/api/phone-numbers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

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

{
  "phoneNumbers": [
    {
      "id": "<string>",
      "accountId": "<string>",
      "did": "<string>",
      "domain": "<string>",
      "provider": "<string>",
      "externalId": "<string>",
      "status": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "organization": {
        "id": "<string>",
        "name": "<string>"
      }
    }
  ]
}

GET

phone-numbers

List Phone Numbers

curl --request GET \
  --url https://api.callhq.ai/api/phone-numbers \
  --header 'x-api-key: <api-key>'

const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};

fetch('https://api.callhq.ai/api/phone-numbers', 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.callhq.ai/api/phone-numbers",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "x-api-key: <api-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"
	"net/http"
	"io"
)

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'

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

{
  "phoneNumbers": [
    {
      "id": "<string>",
      "accountId": "<string>",
      "did": "<string>",
      "domain": "<string>",
      "provider": "<string>",
      "externalId": "<string>",
      "status": true,
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "organization": {
        "id": "<string>",
        "name": "<string>"
      }
    }
  ]
}

Retrieve all phone numbers associated with your organization.

Overview

This endpoint returns a list of all phone numbers configured for your organization, including their status, provider information, and associated metadata.

Request

Headers

Header	Value	Required
`x-api-key`	Your API key	Yes
`accept`	`/`	No

Example Request

curl -X 'GET' \
  'https://api.callhq.ai/api/phone-numbers' \
  -H 'accept: */*' \
  -H 'x-api-key: your_api_key_here'

Response

Success Response (200)

Returns an array of phone number objects.

{
  "phoneNumbers": [
    {
      "id": "1dc31d3f-8e0f-47dd-bfbd-4ac05017b570",
      "accountId": "up-xx-xxxx",
      "did": "91xxxxxx3166",
      "domain": "sip-xx-xx.pliwo.tv",
      "provider": "pliwo",
      "externalId": "aexxxxxx-xxxxxxxx-xxxxxx34579",
      "status": true,
      "createdAt": "2025-07-18T06:52:25.000Z",
      "updatedAt": "2025-07-18T06:52:25.000Z",
      "organization": {
        "id": "e5xxxxxxb-65f7-46cd-b5c3-3bcxxxxx24e",
        "name": "YOUR ORG NAME"
      }
    }
  ]
}

Response Schema

Field	Type	Description
`phoneNumbers`	Array	Array of phone number objects
`id`	String	Unique identifier for the phone number
`accountId`	String	Account identifier
`did`	String	Direct inward dialing number
`domain`	String	SIP domain for the phone number
`provider`	String	Phone number provider (e.g., pliwo, telnyx)
`externalId`	String	External identifier from the provider
`status`	Boolean	Active status of the phone number
`createdAt`	String (ISO 8601)	Creation timestamp
`updatedAt`	String (ISO 8601)	Last update timestamp
`organization.id`	String	Organization identifier
`organization.name`	String	Organization name

Error Responses

Status Code	Description
500	Error fetching phone numbers

Use Cases

Phone Number Management: View all available phone numbers for your organization
Provider Integration: Check which phone number providers are configured
Status Monitoring: Verify the active status of phone numbers
Organization Setup: Review phone number configurations across different accounts

Setup Inbound Agent - Route inbound calls to an assistant
Place Outbound Call - Use a phone number to make outbound calls
List Calls - View call history for specific phone numbers

Authorizations

x-api-key

string

header

required

Response

List of phone numbers retrieved successfully.

phoneNumbers

object[]

Show child attributes

API Documentation

Assistant

Call

Chat

Phone Numbers

Knowledge Base

List Phone Numbers

Overview

Request

Headers

Example Request

Response

Success Response (200)

Response Schema

Error Responses

Use Cases

Authorizations

Response

​Overview

​Request

​Headers

​Example Request

​Response

​Success Response (200)

​Response Schema

​Error Responses

​Use Cases

​Related Endpoints

Authorizations

Response

Overview

Request

Headers

Example Request

Response

Success Response (200)

Response Schema

Error Responses

Use Cases

Related Endpoints