Skip to main content
List Numbers
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: 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.

id
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.

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.

rental
PublicNumberRental · object | null
required

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

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).