List Virtual Numbers

Retrieve all virtual numbers visible to the API key.

GEThttps://api.identitycall.ai/api/v1/public/virtual_numbers

Returns the virtual numbers in the account, filtered by the key's project when project-scoped.

Requires read permission

Scopes

API key scope	Behavior
Account-wide	Returns every virtual number on the account.
Project-scoped	Returns only virtual numbers attached to the key’s bound project.

Query Parameters

This endpoint takes no query parameters. The result set is determined by the API key’s scope.

Request

cURL


curl -X GET "https://api.identitycall.ai/api/v1/public/virtual_numbers" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY"

Python


import requests
import os
 
API_KEY = os.environ.get("IDENTITYCALL_API_KEY")
 
response = requests.get(
    "https://api.identitycall.ai/api/v1/public/virtual_numbers",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
 
numbers = response.json()["data"]
for vn in numbers:
    print(f"{vn['id']}: {vn['phone_number']} ({vn['operators_count']} operators)")

Node.js


const API_KEY = process.env.IDENTITYCALL_API_KEY;
 
const response = await fetch(
  'https://api.identitycall.ai/api/v1/public/virtual_numbers',
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
 
const { data: numbers } = await response.json();
numbers.forEach(vn => {
  console.log(`${vn.id}: ${vn.phone_number} (${vn.operators_count} operators)`);
});

Response

Response200 OK

{
"data": [
  {
    "id": 7,
    "phone_number": "+15551234567",
    "name": "US Sales Line",
    "country_code": "US",
    "active": true,
    "ai_receptionist_enabled": false,
    "operators": [
      { "id": 12, "name": "Alice Carter", "initials": "AC" },
      { "id": 13, "name": "Bob Diaz", "initials": "BD" },
      { "id": 14, "name": "Carol Evans", "initials": "CE" }
    ],
    "operators_count": 3
  },
  {
    "id": 8,
    "phone_number": "+37060012345",
    "name": "LT Support Line",
    "country_code": "LT",
    "active": true,
    "ai_receptionist_enabled": true,
    "operators": [
      { "id": 21, "name": "Daiva Petrauskas", "initials": "DP" }
    ],
    "operators_count": 1
  }
]
}

Response Fields

Field	Type	Description
`id`	integer	Unique virtual number ID
`phone_number`	string	E.164-formatted phone number
`name`	string	Display name (nullable)
`country_code`	string	ISO 3166-1 alpha-2 country code
`active`	boolean	Whether the number is enabled for receiving calls
`ai_receptionist_enabled`	boolean	Whether an AI voice agent answers inbound calls
`operators`	array	Up to the first 3 attached operators (`id`, `name`, `initials`)
`operators_count`	integer	Total operators attached to this number

Errors

Status	Error	Description
401	”Unauthorized”	Missing or invalid API key
403	”Forbidden”	API key lacks `read` permission

Try It

API Key

List Virtual Numbers

Scopes

Query Parameters

Request

cURL

Python

Node.js

Response

Response Fields

Errors

See Also

Try It

Try It