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

const client = new Retell({
  apiKey: 'YOUR_RETELL_API_KEY',
});

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

console.log(phoneNumberResponse.inbound_agent_id);
{
  "phone_number": "+14157774444",
  "phone_number_type": "retell-twilio",
  "last_modification_timestamp": 1703413636133,
  "phone_number_pretty": "+1 (415) 777-4444",
  "inbound_agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "outbound_agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "inbound_agent_version": 1,
  "outbound_agent_version": 1,
  "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.

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"

​
inbound_agent_id
string | null

Unique id of agent to bind to the number. The number will automatically use the agent when receiving inbound calls. If null, this number would not accept inbound call.

Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

​
outbound_agent_id
string | null

Unique id of agent to bind to the number. The number will automatically use the agent when conducting outbound calls. If null, this number would not be able to initiate outbound call without agent id override.

Example:

"oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD"

​
inbound_agent_version
integer | null

Version of the inbound agent to bind to the number. If not provided, will default to latest version.

Example:

1

​
outbound_agent_version
integer | null

Version of the outbound agent to bind to the number. If not provided, will default to latest version.

Example:

1

​
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. If not set or empty, fallback to inbound_agent_id.

​
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. If not set or empty, fallback to outbound_agent_id.

​
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. If not set or empty, fallback to inbound_sms_agent_id.

​
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. If not set or empty, fallback to outbound_sms_agent_id.

​
nickname
string | null

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

Example:

"Frontdesk Number"

​
inbound_webhook_url
string | null

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

Example:

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

​
inbound_sms_webhook_url
string | null

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

Example:

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

​
sip_outbound_trunk_config
object
​
fallback_number
string | null

Enterprise only. Phone number to transfer inbound calls to when organization is in outage mode. 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"