POST
/
create-phone-number
curl --request POST \
  --url https://api.retellai.com/create-phone-number \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json'
{
  "phone_number": "+14157774444",
  "phone_number_pretty": "+1 (415) 777-4444",
  "inbound_agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "outbound_agent_id": "oBeDLoLOeuAbiuaMFXRtDOLriTJ5tSxD",
  "area_code": 415,
  "last_modification_timestamp": 1703413636133
}

Authorizations

Authorization
string
headerrequired

Authentication header containing API key (find it in dashboard). The format is "Bearer YOUR_API_KEY"

Body

application/json
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.

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.

area_code
integer

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

Response

201 - application/json
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_pretty
string
required

Pretty printed phone number, provided for your reference.

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.

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.

area_code
integer
required

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

last_modification_timestamp
integer
required

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