Skip to main content
GET
List phone numbers
This capability is in beta. Behavior can change before general availability.
Filters include search, status, source, health, country, tag and use. Use can be voice, sms_conversations or none. Omitting use lists every number. Page sizes are 10, 20, 50 or 100, with 50 as the default. The key needs Read phone numbers, an organization-wide permission.

Authorizations

Authorization
string
header
required

An API key (tars_sk_…) sent as Authorization: Bearer <key>. Each operation names the permission it needs. Create keys in Settings → Integrations → API keys.

Query Parameters

Text to search for.

status
enum<string>
Available options:
purchasing,
importing,
verifying,
unverified,
active,
suspended,
failed,
releasing,
released
source
enum<string>
Available options:
tars,
twilio_account,
sip
health
enum<string>
Available options:
healthy,
degraded,
failed,
unknown
country
string

ISO country code.

Pattern: ^[A-Z]{2}$
tag
string
use
enum<string>

Absent lists every number.

Available options:
voice,
sms_conversations,
none
limit
enum<integer>
default:50
Available options:
10,
20,
50,
100
cursor
string

The nextCursor of the previous page.

Maximum string length: 1024

Response

One page of results.

One page of a list.

items
object[]
required
nextCursor
string | null
required

Pass it as cursor to read the next page.

hasMore
boolean
required