---
title: "POST /create-phone-number"
method: POST
path: "/create-phone-number"
---

# POST /create-phone-number

`POST /create-phone-number`

Buy a new phone number & Bind agents

## Request body

- object
  - `inbound_agents` AgentWeight[], nullable — 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.
    - `agent_id` string, required
    - `agent_version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
      - integer
      - string
    - `weight` number, required — The weight of the agent. When used in a list of agents, the total weights must add up to 1.
  - `outbound_agents` AgentWeight[], nullable — 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.
    - `agent_id` string, required
    - `agent_version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
      - integer
      - string
    - `weight` number, required — The weight of the agent. When used in a list of agents, the total weights must add up to 1.
  - `area_code` integer — Area code of the number to obtain. Format is a 3 digit integer. Currently only supports US area code.
  - `nickname` string — Nickname of the number. This is for your reference only.
  - `inbound_webhook_url` string, 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_list` string[], 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_list` string[], 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_free` boolean — Whether to purchase a toll-free number. Toll-free numbers incur higher costs.
  - `phone_number` string — 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).
  - `transport` string, nullable — Outbound transport protocol to use for the phone number. Valid values are "TLS", "TCP" and "UDP". Default is "TCP".
  - `fallback_number` string, 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).

## Response `201`

Successfully created a new number.

- PhoneNumberResponse
  - `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.
  - `phone_number_type` 'retell-twilio' | 'retell-telnyx' | 'custom', required — Type of the phone number.
  - `phone_number_pretty` string — Pretty printed phone number, provided for your reference.
  - `allowed_inbound_country_list` string[], 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_list` string[], 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_code` integer — Area code of the number to obtain. Format is a 3 digit integer. Currently only supports US area code.
  - `inbound_agents` AgentWeight[], nullable — 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.
    - `agent_id` string, required
    - `agent_version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
      - integer
      - string
    - `weight` number, required — The weight of the agent. When used in a list of agents, the total weights must add up to 1.
  - `outbound_agents` AgentWeight[], nullable — 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.
    - `agent_id` string, required
    - `agent_version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
      - integer
      - string
    - `weight` number, required — The weight of the agent. When used in a list of agents, the total weights must add up to 1.
  - `inbound_sms_agents` AgentWeight[], nullable — 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.
    - `agent_id` string, required
    - `agent_version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
      - integer
      - string
    - `weight` number, required — The weight of the agent. When used in a list of agents, the total weights must add up to 1.
  - `outbound_sms_agents` AgentWeight[], nullable — 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.
    - `agent_id` string, required
    - `agent_version` union — Agent version reference. Supports a numeric version (for example 3) or a tag/environment name (for example "prod"). The string "latest" resolves to the most recently created version (the largest version number), and "latest_published" resolves to the most recently published version. When a tag is provided, resolution uses that exact tag assignment (including its dynamic variables). If the tag exists but is currently unassigned, it resolves to latest. When a numeric version, latest, or latest_published is provided, resolution applies dynamic variables from the preferred tag for that resolved version (most recently assigned), if any.
      - integer
      - string
    - `weight` number, required — The weight of the agent. When used in a list of agents, the total weights must add up to 1.
  - `nickname` string, nullable — Nickname of the number. This is for your reference only.
  - `inbound_webhook_url` string, 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_url` string, 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_timestamp` integer, required — Last modification timestamp (milliseconds since epoch). Either the time of last update or creation if no updates available.
  - `sip_outbound_trunk_config` object, nullable
    - `termination_uri` string, nullable — The termination URI for the SIP trunk for the phone number.
    - `auth_username` string, nullable — The username used for authenticating the SIP trunk for the phone number.
    - `transport` string, nullable — Outbound transport protocol for the SIP trunk for the phone number. Valid values are "TLS", "TCP" and "UDP". Default is "TCP".
  - `fallback_number` string, 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).

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `500` — Internal Server Error

---

[API](https://skmtc.net/retellai/apis/retell-sdk.md) · [All operations](https://skmtc.net/retellai/apis/retell-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/retellai/retell-sdk/versions/2a182bedbfc5/schema)