Skip to main content
GET
/
get-phone-number
/
{phone_number}
JavaScript
import Retell from 'retell-sdk';

const client = new Retell({
  apiKey: process.env['RETELL_API_KEY'], // This is the default and can be omitted
});

const phoneNumberResponse = await client.phoneNumber.retrieve('+14157774444');

console.log(phoneNumberResponse.last_modification_timestamp);
{
  "phone_number": "+14157774444",
  "phone_number_type": "retell-twilio",
  "last_modification_timestamp": 1703413636133,
  "phone_number_pretty": "+1 (415) 777-4444",
  "allowed_inbound_country_list": [
    "US",
    "CA",
    "GB"
  ],
  "allowed_outbound_country_list": [
    "US",
    "CA"
  ],
  "area_code": 415,
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": 1
    }
  ],
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": 1
    }
  ],
  "inbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": 1
    }
  ],
  "outbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "weight": 0.5,
      "agent_version": 1
    }
  ],
  "nickname": "Frontdesk Number",
  "inbound_webhook_url": "https://example.com/inbound-webhook",
  "inbound_sms_webhook_url": "https://example.com/inbound-sms-webhook",
  "sip_outbound_trunk_config": {
    "termination_uri": "someuri.pstn.twilio.com",
    "auth_username": "username",
    "transport": "TCP"
  },
  "fallback_number": "+14155551234"
}

Authorizations

​
Authorization
string
header
required

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Path Parameters

​
phone_number
string
required

E.164 format of the number (+country code, then number with no space, no special characters), used as the unique identifier for phone number APIs.

Minimum string length: 1
Example:

"+14157774444"

Response

Successfully retrieved a phone number.

​
phone_number
string
required

E.164 format of the number (+country code, then number with no space, no special characters), used as the unique identifier for phone number APIs.

Example:

"+14157774444"

​
phone_number_type
enum<string>
required

Type of the phone number.

Available options:
retell-twilio,
retell-telnyx,
custom
Example:

"retell-twilio"

​
last_modification_timestamp
integer
required

Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.

Example:

1703413636133

​
phone_number_pretty
string

Pretty printed phone number, provided for your reference.

Example:

"+1 (415) 777-4444"

​
allowed_inbound_country_list
string[] | null

List of ISO 3166-1 alpha-2 country codes from which inbound calls are allowed. If not set or empty, calls from all countries are allowed.

Example:
["US", "CA", "GB"]
​
allowed_outbound_country_list
string[] | null

List of ISO 3166-1 alpha-2 country codes to which outbound calls are allowed. If not set or empty, calls to all countries are allowed.

Example:
["US", "CA"]
​
area_code
integer

Area code of the number to obtain. Format is a 3 digit integer. Currently only supports US area code.

Example:

415

​
inbound_agents
object[] | null

Inbound agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each inbound call, with probability proportional to the weight. Total weights must add up to 1.

​
outbound_agents
object[] | null

Outbound agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each outbound call, with probability proportional to the weight. Total weights must add up to 1.

​
inbound_sms_agents
object[] | null

Inbound SMS agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each inbound SMS, with probability proportional to the weight. Total weights must add up to 1.

​
outbound_sms_agents
object[] | null

Outbound SMS agents to bind to the number with weights. If set and non-empty, one agent will be picked randomly for each outbound SMS, with probability proportional to the weight. Total weights must add up to 1.

​
nickname
string | null

Nickname of the number. This is for your reference only.

Example:

"Frontdesk Number"

​
inbound_webhook_url
string | null

If set, Retell will send a webhook for inbound calls, where you can override the agent ID, set dynamic variables, and configure other fields specific to that call.

Example:

"https://example.com/inbound-webhook"

​
inbound_sms_webhook_url
string | null

If set, Retell will send a webhook for inbound SMS, where you can override the agent ID, set dynamic variables, and configure other fields specific to that chat.

Example:

"https://example.com/inbound-sms-webhook"

​
sip_outbound_trunk_config
object
​
fallback_number
string | null

When inbound call concurrency is reached and a slot does not free up after extended ringing, the call will fall back to this number. Can be either a Retell phone number or an external number. Cannot be the same as this phone number, and cannot be a number that already has its own fallback configured (prevents nested forwarding).

Example:

"+14155551234"