Skip to the content

Read a Phone number and its routing

GET /v1/phone-numbers/{phone_number_id}

Property	Value
Operation	`get_phone_number`
Group	Phone numbers
Scope	`telephony:read`
Route class	`read`
Idempotency	No `Idempotency-Key`
Audit	Not audited: A configuration read; a Phone number is the Organization's own number, not Call content.
Released in	1.22.0
Phase 0 host	Served (the hosted api pins 1.65.0)

Answers the Phone number with its revision as the ETag (1.22.0).

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the telephony:read scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl "$VOCAL_API/v1/phone-numbers/pn_..." \
  -H "Authorization: Bearer $VOCAL_API_KEY"

const response = await fetch(`${process.env.VOCAL_API}/v1/phone-numbers/pn_...`, {
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
  },
});
console.log(response.status, await response.text());

import os

import requests

response = requests.get(
    f"{os.environ['VOCAL_API']}/v1/phone-numbers/pn_...",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
    },
)
print(response.status_code, response.text)

Parameters

Name	In	Type	Required	Description
`phone_number_id`	path	PhoneNumberId	yes	The id of a Phone number: `pn_` and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log.

Responses

Status	Content type	Shape	Error codes
`200`	`application/json`	PhoneNumber
`400`	`application/json`	ErrorEnvelope	`invalid_request`
`401`	`application/json`	ErrorEnvelope	`unauthenticated`
`403`	`application/json`	ErrorEnvelope	`forbidden`
`404`	`application/json`	ErrorEnvelope	`not_found`
`429`	`application/json`	ErrorEnvelope	`rate_limited`
`500`	`application/json`	ErrorEnvelope	`internal_error`

Fields of the `200` answer

The shape is PhoneNumber.

Field	Type	Required	Description
`agent_id`	AgentId or null	yes	The Agent that inbound Calls to the number run (1.22.0). Null when the number routes to no Agent: every inbound Call to it is then refused and recorded with the ended reason `refused_no_route`.
`agent_version`	integer or null	yes	The published version of the Agent that every inbound Call to the number runs, or null to run the Agent's active version as it stands when each Call is admitted. (1.22.0)
`capabilities`	array of PhoneNumberCapability	yes	What the number may carry, each capability once (1.22.0).
`created_at`	Timestamp	yes
`display`	string	yes	The number masked: the country calling code, a space-separated elision and the last four digits, such as `+1 ... 2486`, the form of a Call's `destination_hint` (1.22.0). Show it wherever the full number is not needed.
`e164`	string	yes	The full number in E.164 form (1.22.0). Only the routes that need `telephony:read` answer a Phone number, so only a holder of that permission receives it. It is never logged and never written to an Audit event.
`id`	PhoneNumberId	yes
`inbound_media_encryption`	SipMediaEncryption or null	no	The media encryption the inbound LiveKit SIP trunk holds now (1.34.0), read-only: an operator changes it by provisioning again, never through the api. Null when the api could not read the trunk; a reader treats its absence as null, as from an api before 1.34.0.
`object`	`"phone_number"`	yes
`outbound_media_encryption`	SipMediaEncryption or null	no	The media encryption the number's outbound trunk holds now (1.34.0), read-only. Null when the number has no outbound trunk, which a number without the `outbound` capability does not, or when the api could not read it; a reader treats its absence as null.
`outbound_transport`	SipTransport or null	no	The SIP transport the number's outbound trunk holds now (1.34.0), read-only; null as `outbound_media_encryption` is. The inbound trunk has none, because the carrier chooses it.
`revision`	integer	yes	Counts writes to the Phone number (1.22.0); returned as the ETag and required in the If-Match of the update.
`sip_trunk_id`	SipTrunkId	yes	The SIP trunk the number is reached on (1.22.0).
`status`	PhoneNumberStatus	yes
`updated_at`	Timestamp	yes