POST /import-phone-number — retell-sdk

Import a phone number from custom telephony & Bind agents

post/import-phone-number

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.

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, will send a webhook for inbound calls, where you can to override agent id, set dynamic variables and other fields specific to that call.

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,
  "termination_uri": "someuri.pstn.twilio.com",
  "sip_trunk_auth_username": "username",
  "sip_trunk_auth_password": "123456",
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 0.5
    }
  ],
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "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

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.

inbound_sms_webhook_urlstring nullable

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.

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

Enterprise only. Phone number to transfer inbound calls to when organization is in outage mode or when an inbound call cannot get a concurrency slot before the fallback timeout. 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 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": 1,
      "weight": 0.5
    }
  ],
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 0.5
    }
  ],
  "inbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 0.5
    }
  ],
  "outbound_sms_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "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"
  },
  "fallback_number": "+14155551234"
}

Changes

Changed in 9 of the 28 revisions of this API.91631

May 28, 202640402ca870b924See the full diff
- ●
  changed the pattern of the request property /// from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$
  request-property-pattern-changed
- ●
  changed the pattern of the request property /// from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$
  request-property-pattern-changed
- ○
  the /// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the /// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the /// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the /// response's property pattern was changed from ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ to ^(latest|latest_published|(?!(?:latest|latest_published|v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
May 8, 20267dd16ddf69d824See the full diff
- ●
  changed the pattern of the request property /// from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$
  request-property-pattern-changed
- ●
  changed the pattern of the request property /// from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$
  request-property-pattern-changed
- ○
  the /// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the /// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the /// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
- ○
  the /// response's property pattern was changed from ^[a-z0-9_-]+$ to ^(latest|(?!(?:v\d+)$)[a-z][a-z0-9_-]{0,19})$ for the status
  response-property-pattern-changed
May 7, 2026f1a0d7c1e36c42See the full diff
- ▲
  response property inbound_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 201
  response-property-list-of-types-widened
- ▲
  response property inbound_sms_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 201
  response-property-list-of-types-widened
- ▲
  response property outbound_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 201
  response-property-list-of-types-widened
- ▲
  response property outbound_sms_agents/items/agent_version list-of-types was widened by adding types string to media type application/json of response 201
  response-property-list-of-types-widened
- ○
  request property // list-of-types was widened by adding types string to media type application/json
  request-property-list-of-types-widened
- ○
  request property // list-of-types was widened by adding types string to media type application/json
  request-property-list-of-types-widened
Apr 20, 20268ee53928bf318See the full diff
- ●
  removed the request property
  request-property-removed
- ●
  removed the request property
  request-property-removed
- ●
  removed the request property
  request-property-removed
- ●
  removed the request property
  request-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
Mar 19, 20263aa6f6e028ef1See the full diff
- ○
  added the new optional request property
  new-optional-request-property
Mar 9, 20268fbf8c54a1425See the full diff
- ▲
  the request property's minLength was increased from 0 to 1
  request-property-min-length-increased
- ▲
  the // request property's minLength was increased from 0 to 1
  request-property-min-length-increased
- ▲
  the request property's minLength was increased from 0 to 1
  request-property-min-length-increased
- ▲
  the // request property's minLength was increased from 0 to 1
  request-property-min-length-increased
- ▲
  the request property's minLength was increased from 0 to 1
  request-property-min-length-increased
Feb 23, 2026bcff6899fa2a8See the full diff
- ○
  request property deprecated
  request-property-deprecated
- ○
  request property deprecated
  request-property-deprecated
- ○
  request property deprecated
  request-property-deprecated
- ○
  request property deprecated
  request-property-deprecated
- ○
  response property inbound_agent_id deprecated
  response-property-deprecated
- ○
  response property inbound_agent_version deprecated
  response-property-deprecated
- ○
  response property outbound_agent_id deprecated
  response-property-deprecated
- ○
  response property outbound_agent_version deprecated
  response-property-deprecated
Feb 6, 2026dfad228ab4a48See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jan 23, 2026427e77039f3944See the full diff
- ●
  removed the request property
  request-property-removed
- ●
  removed the request property
  request-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added

Full history