Skip to main content
GET
/
phone-numbers
List phone numbers
curl --request GET \
  --url https://api.instaview.sk/phone-numbers \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "number": "+14155552671",
      "companyId": "123e4567-e89b-12d3-a456-426614174000",
      "capabilities": "OUTBOUND",
      "custom": false,
      "provider": "TWILIO",
      "status": "AVAILABLE",
      "numberType": "LOCAL",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-06-01T08:00:00.000Z",
      "location": "New York, US"
    }
  ],
  "total": 3,
  "page": 1,
  "limit": 20,
  "totalPages": 1
}
Lists all active phone numbers assigned to the API key’s company.

​
Overview

The list phone numbers endpoint returns all phone numbers currently assigned to your company. Use the phone number id field when configuring agents for outbound or inbound calls.

​
Use Cases

  • Agent Configuration: Retrieve phone number IDs before creating or updating agents
  • Number Inventory: Audit which numbers are assigned to your company
  • Capability Check: Verify whether numbers support outbound, inbound, or both call directions

​
ATS Keys

ATS partner keys must supply the companyId query parameter to specify which child company’s phone numbers to list. Regular company API keys automatically scope the response to their own company.

​
Basic Usage

GET /phone-numbers

​
With Pagination

// Get a specific page
GET /phone-numbers?page=2&limit=50

// Response includes pagination metadata
{
  "data": {
    "data": [...],
    "total": 5,
    "page": 2,
    "limit": 50,
    "totalPages": 1
  }
}

​
Finding a Phone Number for an Agent

// Retrieve phone numbers and pick one for agent configuration
async function getPhoneNumberForAgent() {
  const response = await fetch("https://api.instaview.sk/phone-numbers", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  const { data } = await response.json();

  // Use the `id` field when creating or updating an agent
  const outbound = data.data.find(
    (pn) =>
      pn.capabilities === "OUTBOUND" || pn.capabilities === "INBOUND_OUTBOUND",
  );
  return outbound?.id;
}

​
ATS Key Example

// ATS partner key — scope to a specific child company
GET /phone-numbers?companyId=123e4567-e89b-12d3-a456-426614174000

Authorizations

​
Authorization
string
header
required

API key for authentication using Bearer scheme

Query Parameters

​
page
integer
default:1

Page number (1-based)

Required range: 1 <= x <= 10000
Example:

1

​
limit
integer
default:20

Number of items per page

Required range: 1 <= x <= 100
Example:

20

​
companyId
string<uuid>

Company ID (required for ATS keys, optional for regular keys)

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

200 - application/json
​
data
object[]
required

Array of phone numbers

​
total
number
required

Total number of items

Example:

3

​
page
number
required

Current page number

Example:

1

​
limit
number
required

Number of items per page

Example:

20

​
totalPages
number
required

Total number of pages

Example:

1