POST
/
v1
/
inbound
/
{phone_number}
curl --request POST \
  --url https://api.bland.ai/v1/inbound/{phone_number} \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '{
  "prompt": "<string>",
  "transfer_list": {},
  "model": "<string>",
  "transfer_phone_number": "<string>",
  "voice_id": 123,
  "reduce_latency": true,
  "webhook": "<string>",
  "record": true,
  "first_sentence": "<string>",
  "tools": [
    {}
  ],
  "dynamic_data": {},
  "interruption_threshold": {},
  "max_duration": {}
}'
{
    "status": "success",
    "message": "Successfully updated number +18584139939.",
    "updates": {
        "prompt": "(Your prompt)",
        "voice_id": 1,
        "webhook": null,
        "first_sentence": "Roberta speaking, how can I help you?",
        "reduce_latency": false,
        "record": false,
        "max_duration": 30,
        "model": "turbo",
        //...
    }
}

Headers

authorization
string
required

Your API key for authentication.

Path Parameters

phone_number
string

The inbound phone number you wish to update.

Formatting Notes:

  • The '+' or '%2B' prefix is optional.
  • Will assume a US country code if no country code is provided.

Valid Examples for +13334445555:

  • %2B13334445555
  • 13334445555
  • 3334445555

Body

prompt
string
required

Provide instructions, relevant information, and examples of the ideal conversation flow.

For inbound numbers, consider including additional context about the purpose of the call, and what types of callers to expect.

transfer_list
object

Give your agent the ability to transfer calls to a set of phone numbers.

Overrides transfer_phone_number if a transfer_list.default is specified.

Will default to transfer_list.default, or the chosen phone number.

Example usage to route calls to different departments:

"transfer_list": {
    "default": "+12223334444",
    "sales": "+12223334444",
    "support": "+12223334444",
    "billing": "+12223334444"
}
model
string
default: "enhanced"

Select a model to use for your call.

Options: base, turbo and enhanced.

In nearly all cases, enhanced is the best choice for now.

transfer_phone_number
string

A phone number that the agent can transfer to under specific conditions - such as being asked to speak to a human or supervisor.

Set to null to remove.

voice_id
integer

Set your agent’s voice - all available voices can be found with the List Voices endpoint.

reduce_latency
boolean
default: "true"

Reducing latency means that the agent will generate responses more quickly and have less of a delay. This must be set to true when using Voice Clones.

webhook
string

The webhook should be a http / https callback url. We will send the call_id and transcript to this URL after the call completes. This can be useful if you want to have real time notifications when calls finish.

Set to null or an empty string to clear the webhook.

record
boolean
default: "false"

To record your phone call, set record to true. When your call completes, you can access through the recording_url field in the call details or your webhook.

first_sentence
string

A phrase that your call will start with instead of a generating one on the fly. This works both with and without wait_for_greeting. Can be more than one sentence, but must be less than 200 characters.

To remove, set to null or an empty string.

tools
array

Interact with the real world through API calls.

Detailed tutorial here: Custom Tools

voice_settings
Voice Settings Object

Alter advanced voice settings for your agent.

To remove, set to null or an empty string.

dynamic_data
object

Integrate data from external APIs into your agent’s knowledge.

Set to null or an empty string to clear dynamic data settings.

Detailed usage in the Send Call endpoint.

interruption_threshold
integer (milliseconds)
default: 50

When you increase the interruption latency, you force the AI phone agent to listen longer before responding. In practice, increasing the threshold results in less interruptions and more latency.

Try setting the threshold to 500 milliseconds. You’ll encounter higher latency, but you’ll be interrupted less frequently.

Set to null to reset to default.

max_duration
integer (minutes)
default: 30

The maximum duration that calls to your agent can last before being automatically terminated.

Set to null to reset to default.

Response

status
string

Whether the update was successful or not - will be success or error.

message
string

A message describing the status of the update.

updates
object

An object containing the updated settings for the inbound number.

failed_updates
object

If the update was unsuccessful, this will contain the settings that failed to update. Useful to determine how your request is being interpreted on our end.