List phone numbers

GET

numbers

List Numbers

curl --request GET \
  --url https://api.vocily.ai/v1/numbers \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vocily.ai/v1/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.vocily.ai/v1/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 => [
    "Authorization: Bearer <token>"
  ],
]);

$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.vocily.ai/v1/numbers"

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

	req.Header.Add("Authorization", "Bearer <token>")

	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.vocily.ai/v1/numbers")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

[
  {
    "id": "00000003-0000-4000-8000-000000000003",
    "number": "+919876500000",
    "carrier_status": "active",
    "source": "byoc",
    "provider": "plivo",
    "provider_sid": null,
    "connection_id": "00000004-0000-4000-8000-000000000004",
    "lifecycle_status": "active",
    "country_iso": null,
    "number_type": null,
    "inbound_agent": {
      "id": "00000002-0000-4000-8000-000000000002",
      "name": "zdfbdhjfbdkfbdkjfbkdjfb"
    },
    "outbound_agents": [
      {
        "id": "00000002-0000-4000-8000-000000000002",
        "name": "zdfbdhjfbdkfbdkjfbkdjfb"
      }
    ],
    "rental": null,
    "created_at": "2026-09-12T22:45:02.810506Z",
    "updated_at": "2026-09-12T23:02:43.014234Z"
  }
]

{
  "detail": "Invalid API key",
  "code": "UNAUTHORIZED"
}

{
  "detail": {
    "code": "validation_error",
    "message": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>",
        "type": "<string>"
      }
    ]
  },
  "code": "VALIDATION_ERROR"
}

{
  "code": "rate_limited"
}

status is inactive when the number is no longer present in its carrier account - a call placed from it will fail. Buying, releasing and assigning numbers are dashboard-only actions.

Where the number came from

Two fields answer this, and they mean different things:


`source`	`vocily` - you rent it from us. `byoc` - it sits on a carrier account you connected yourself.
`provider`	`vocily` for a number you rent from us. For a BYOC number, the carrier carrying it (`plivo`, `vobiz`, …).

rental is populated only for source: "vocily" and carries monthly_price, renewal_date and rented_at. It is null for a BYOC number, where your own carrier bills you directly. provider_sid and connection_id identify the number and the account inside your carrier account, so they are populated for BYOC and null for a number you rent from us. connection_id is what tells two of your own carrier accounts apart - provider cannot, since both would read plivo. It is opaque: no endpoint resolves it to a name, so group numbers by it rather than trying to look it up.

provider, number_type and lifecycle_status are open sets - new values will be added. Treat them as strings, not as an exhaustive list.

Authorizations

Authorization

string

header

required

Your API key as a Bearer token, e.g. Authorization: Bearer vk_….

Response

The numbers assigned to this workspace.

string

required

Our stable id for this number. Prefer it over number as a key: an E.164 is re-rentable and a released number keeps its row.

number

string

required

The number itself, E.164.

carrier_status

string

required

active or inactive — whether the number is still present in its own carrier account. An inactive number will fail if you dial from it. A different question from lifecycle_status: a number you still rent reads active here only while the carrier lists it, and a carrier outage never changes its rental state.

source

string

required

vocily if you rent it from us, byoc if you brought your own carrier account.

provider

string

required

The carrier your number runs on. vocily for a number you rent from us. Your own carrier is named (plivo, vobiz) when source is byoc. Unstable enum: it grows as we support more carriers, so never switch exhaustively on it.

provider_sid

string | null

required

The carrier's own identifier. null for a number you rent from us, where the id lives in our account.

connection_id

string | null

required

Which of your own carrier accounts this number is attached to, when source is byoc — it tells two of your accounts apart, which provider alone cannot. Opaque: no endpoint resolves it to a name, so group by it rather than looking it up. null for a number you rent from us.

lifecycle_status

string

required

Where the number is in its rental life with us — pending, active, failed, releasing, released. A released number keeps its row as a billing record. Open set. A different question from status, which is carrier presence.

country_iso

string | null

required

ISO country code the number belongs to.

number_type

string | null

required

How the carrier classified it at purchase — local, mobile, tollfree. Unstable enum: never switch exhaustively on it.

inbound_agent

PublicNumberAgent · object | null

required

The agent answering INBOUND on this number, if any.

Show child attributes

outbound_agents

PublicNumberAgent · object[]

required

Agents that dial OUT from this number, read from each agent's LIVE version — an unpublished draft never appears here.

Show child attributes

rental

PublicNumberRental · object | null

required

Billing detail for a number you rent from us. null for BYOC, which you pay your own carrier for.

Show child attributes

created_at

string<date-time>

required

When the number was added to your workspace (UTC, ISO 8601).

updated_at

string<date-time>

required

When its record last changed (UTC, ISO 8601).

List Numbers

curl --request GET \
  --url https://api.vocily.ai/v1/numbers \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.vocily.ai/v1/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.vocily.ai/v1/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 => [
    "Authorization: Bearer <token>"
  ],
]);

$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.vocily.ai/v1/numbers"

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

	req.Header.Add("Authorization", "Bearer <token>")

	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.vocily.ai/v1/numbers")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

[
  {
    "id": "00000003-0000-4000-8000-000000000003",
    "number": "+919876500000",
    "carrier_status": "active",
    "source": "byoc",
    "provider": "plivo",
    "provider_sid": null,
    "connection_id": "00000004-0000-4000-8000-000000000004",
    "lifecycle_status": "active",
    "country_iso": null,
    "number_type": null,
    "inbound_agent": {
      "id": "00000002-0000-4000-8000-000000000002",
      "name": "zdfbdhjfbdkfbdkjfbkdjfb"
    },
    "outbound_agents": [
      {
        "id": "00000002-0000-4000-8000-000000000002",
        "name": "zdfbdhjfbdkfbdkjfbkdjfb"
      }
    ],
    "rental": null,
    "created_at": "2026-09-12T22:45:02.810506Z",
    "updated_at": "2026-09-12T23:02:43.014234Z"
  }
]

{
  "detail": "Invalid API key",
  "code": "UNAUTHORIZED"
}

{
  "detail": {
    "code": "validation_error",
    "message": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>",
        "type": "<string>"
      }
    ]
  },
  "code": "VALIDATION_ERROR"
}

{
  "code": "rate_limited"
}

Calls

Chats

Phone Numbers

Knowledge Bases

Files

Agents

Speech

Catalogues

Integrations

Custom Analysis

Memory

Widget

Webhooks

List phone numbers

Where the number came from

Authorizations

Response