POST /import-phone-number

Changed on Oct 29, 2026

Import a phone number from custom telephony & Bind agents

Request

Base URL
https://api.retellai.com
Auth
HTTP bearer

Request body

phone_numberstring required

The number you are trying to import in 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.

ignore_e164_validationboolean

If true, E.164 validation for phone_number is skipped. This is useful for internal pseudo numbers when using custom telephony. If omitted, default is true. Must be a boolean literal; string values like "true" or "false" are invalid.

codecsstring[]

SIP codec preferences for custom phone numbers only, used for inbound and outbound gateway calls. Retell-managed Twilio and Telnyx phone numbers do not support this setting. An empty list uses the gateway's default codecs. Codec names are extensible and are not limited to the examples.

termination_uristring required

The termination uri to uniquely identify your elastic SIP trunk. This is used for outbound calls. For Twilio elastic SIP trunks it always end with ".pstn.twilio.com".

sip_trunk_auth_usernamestring

The username used for authentication for the SIP trunk.

sip_trunk_auth_passwordstring

The password used for authentication for the SIP trunk.

nicknamestring

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

inbound_webhook_urlstring nullable

If set, Retell will send a webhook for inbound calls, where you can override the agent ID, set dynamic variables, reject the call, and configure other fields specific to that call. Includes call_inbound.call_id for deduplication across HTTP retries. Early setup failures may not create a call history record.

allowed_inbound_country_liststring[] nullable

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.

allowed_outbound_country_liststring[] nullable

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.

transportstring nullable

Outbound transport protocol to update for the phone number. Valid values are "TLS", "TCP" and "UDP". Default is "TCP".

Example request

{
  "phone_number": "+14157774444",
  "ignore_e164_validation": true,
  "codecs": [
    "PCMU",
    "PCMA",
    "G.722"
  ],
  "termination_uri": "someuri.pstn.twilio.com",
  "sip_trunk_auth_username": "username",
  "sip_trunk_auth_password": "123456",
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": "latest_published",
      "weight": 0.5
    }
  ],
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": "latest_published",
      "weight": 0.5
    }
  ],
  "nickname": "Frontdesk Number",
  "inbound_webhook_url": "https://example.com/inbound-webhook",
  "allowed_inbound_country_list": [
    "US",
    "CA",
    "GB"
  ],
  "allowed_outbound_country_list": [
    "US",
    "CA"
  ],
  "transport": "TCP"
}

Response

Successfully imported a number.

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

phone_number_type'retell-twilio' | 'retell-telnyx' | 'custom' required

Type of the phone number.

phone_number_prettystring

Pretty printed phone number, provided for your reference.

allowed_inbound_country_liststring[] nullable

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.

allowed_outbound_country_liststring[] nullable

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.

area_codeinteger

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

nicknamestring nullable

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

inbound_webhook_urlstring nullable

inbound_sms_webhook_urlstring nullable

If set, Retell will send a webhook for inbound SMS, where you can override the agent ID, set dynamic variables, reject the SMS, and configure other fields specific to that chat. Includes chat_inbound.chat_id for deduplication across HTTP retries. Early setup failures may not create a chat history record.

last_modification_timestampinteger required

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

fallback_numberstring nullable

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

inbound_fallback_enabledboolean

Whether inbound fallback is enabled for this phone number. When enabled, inbound calls are transferred to the fallback number.

Example response

{
  "phone_number": "+14157774444",
  "phone_number_type": "retell-twilio",
  "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",
      "agent_version": "latest_published",
      "weight": 0.5
    }
  ],
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": "latest_published",
      "weight": 0.5
    }
  ],
  "inbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": "latest_published",
      "weight": 0.5
    }
  ],
  "outbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": "latest_published",
      "weight": 0.5
    }
  ],
  "nickname": "Frontdesk Number",
  "inbound_webhook_url": "https://example.com/inbound-webhook",
  "inbound_sms_webhook_url": "https://example.com/inbound-sms-webhook",
  "last_modification_timestamp": 1703413636133,
  "sip_outbound_trunk_config": {
    "termination_uri": "someuri.pstn.twilio.com",
    "auth_username": "username",
    "transport": "TCP",
    "codecs": [
      "PCMU",
      "PCMA",
      "G.722"
    ]
  },
  "fallback_number": "+14155551234"
}

Changes

Oct 29, 20261cd9a6305ed5 Revision changes
- info
  added the optional property to the response with the status
Oct 22, 202603068635e977 Revision changes
- info
  added the new optional request property
- info
  added the optional property / to the response with the status

Operation history (11 revisions)