Sign in

v28

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-05-2887246443.7 KB

Buy a new phone number & Bind agents

post/create-phone-number

Request body

area_codeinteger

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

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.

number_provider'twilio' | 'telnyx'

The provider to purchase the phone number from. Default to twilio.

country_code'US' | 'CA'

The ISO 3166-1 alpha-2 country code of the number you are trying to purchase. If left empty, will default to "US".

toll_freeboolean

Whether to purchase a toll-free number. Toll-free numbers incur higher costs.

phone_numberstring

The number you are trying to purchase in E.164 format of the number (+country code then number with no space and no special characters).

transportstring nullable

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

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 request

{
  "inbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 0.5
    }
  ],
  "outbound_agents": [
    {
      "agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
      "agent_version": 1,
      "weight": 0.5
    }
  ],
  "area_code": 415,
  "nickname": "Frontdesk Number",
  "inbound_webhook_url": "https://example.com/inbound-webhook",
  "allowed_inbound_country_list": [
    "US",
    "CA",
    "GB"
  ],
  "allowed_outbound_country_list": [
    "US",
    "CA"
  ],
  "number_provider": "twilio",
  "country_code": "US",
  "phone_number": "+14157774444",
  "transport": "TCP",
  "fallback_number": "+14155551234"
}

Response

Successfully created a new 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"
}