POST
/
v1
/
inbound
/
{phone_number}
Update Inbound Number Details
curl --request POST \
  --url https://api.bland.ai/v1/inbound/{phone_number} \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '{
  "prompt": "<string>",
  "pathway_id": "<string>",
  "pathway_version": 123,
  "voice": "<string>",
  "background_track": "<string>",
  "first_sentence": "<string>",
  "summary_prompt": "<string>",
  "wait_for_greeting": true,
  "interruption_threshold": 123,
  "model": "<string>",
  "request_data": {},
  "tools": [
    {}
  ],
  "language": "<string>",
  "timezone": "<string>",
  "transfer_phone_number": "<string>",
  "transfer_list": {},
  "dynamic_data": {},
  "keywords": [
    "<string>"
  ],
  "noise_cancellation": true,
  "ignore_button_press": true,
  "max_duration": 123,
  "webhook": "<string>",
  "webhook_events": [
    "<string>"
  ],
  "analysis_schema": {},
  "metadata": {},
  "analysis_prompt": "<string>",
  "record": true,
  "citation_schema_ids": [
    "<string>"
  ]
}'
{
    "status": "success",
    "message": "Successfully updated number +18584139939.",
    "updates": {
        "prompt": "(Your prompt)",
        "voice": "maya",
        "webhook": null,
        "first_sentence": "Roberta speaking, how can I help you?",
        "record": false,
        "max_duration": 30,
        "model": "base",
        //...
    }
}

​
Headers

​
authorization
string
required
Your API key for authentication.
​
encrypted_key
string
The encrypted_key for the Twilio account that owns the phone number you want to modify. Not required if you are using a Bland phone number.

​
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.
​
pathway_id
string
Set the pathway that your agent will follow. This will override the prompt field, so there is no need to pass the ‘prompt’ field if you are setting a pathway.Warning: Setting a pathway will set the following fields to null / their default value - prompt, first_sentence, model, dynamic_data, tools, transfer_listSet to null or an empty string to clear the pathway.
​
pathway_version
integer
The version number of the pathway to use for the call. Defaults to the production version.

​
Agent Parameters (Body)

​
voice
string
Set your agent’s voice - all available voices can be found with the List Voices endpoint.
​
background_track
string
Select an audio track that you’d like to play in the background during the call. The audio will play continuously when the agent isn’t speaking, and is incorporated into it’s speech as well.Use this to provide a more natural, seamless, engaging experience for the conversation. We’ve found this creates a significantly smoother call experience by minimizing the stark differences between total silence and the agent’s speech.Options:
  • null - Default, will play audible but quiet phone static.
  • office - Office-style soundscape. Includes faint typing, chatter, clicks, and other office sounds.
  • cafe - Cafe-like soundscape. Includes faint talking, clinking, and other cafe sounds.
  • restaurant - Similar to cafe, but more subtle.
  • none - Minimizes background noise
​
first_sentence
string
Makes your agent say a specific phrase or sentence for its first response.
​
summary_prompt
string
(Optional) Custom instructions for how the call summary should be generated after the call completes. Use this to provide specific guidance or context for the AI when writing the post-call summary. Maximum length: 2000 characters.Example:
{
  "summary_prompt": "Summarize the call in 2-3 sentences, focusing on the customer's main concern and any next steps discussed."
}
​
wait_for_greeting
boolean
default:false
By default, the agent starts talking as soon as the call connects.When wait_for_greeting is set to true, the agent will wait for the call recipient to speak first before responding.
​
interruption_threshold
number
default:100
Adjusts how patient the AI is when waiting for the user to finish speaking.Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding.Recommended range: 50-200
  • 50: Extremely quick, back and forth conversation
  • 100: Balanced to respond at a natural pace
  • 200: Very patient, allows for long pauses and interruptions. Ideal for collecting detailed information.
Try to start with 100 and make small adjustments in increments of ~10 as needed for your use case.
​
model
string
default:"base"
Select a model to use for your call.Options: base or turbo.In nearly all cases, base is the best choice for now.
​
request_data
object
default:"{}"
Request data fields are available to the AI agent during the call when referenced in the associated pathway or task. This data is accessible in variables if the call is answered. For example, let’s say in your app you want to programmatically set the name of the person you’re calling. You could set request_data to:
Example
  {
    "task": "Say hello to the user, who's name is {{name}}", // also works in the prompt, tools, etc.
    "request_data": {
      "name": "John Doe"
    }
  }
​
tools
array
Interact with the real world through API calls.Detailed tutorial here: Custom Tools
​
language
string
default:"en-US"
Select a supported language of your choice. Optimizes every part of our API for that language - transcription, speech, and other inner workings.
​
timezone
string
default:"America/Los_Angeles"
Set the timezone for the call. Handled automatically for calls in the US.This helps significantly with use cases that rely on appointment setting, scheduling, or behaving differently based on the time of day.Timezone options are here in the TZ identifier column.
​
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.
​
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"
}
​
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
number
default:100
Adjusts how patient the AI is when waiting for the user to finish speaking.Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding.Recommended range: 50-200
  • 50: Extremely quick, back and forth conversation
  • 100: Balanced to respond at a natural pace
  • 200: Very patient, allows for long pauses and interruptions. Ideal for collecting detailed information.
Try to start with 100 and make small adjustments in increments of ~10 as needed for your use case.
​
keywords
string[]
default:"[]"
These words will be boosted in the transcription engine - recommended for proper nouns or words that are frequently mis-transcribed.For example, if the word “Reece” is frequently transcribed as a homonym like “Reese” you could do this:
{
  "keywords": ["Reece"]
}
For stronger keyword boosts, you can place a colon then a boost factor after the word. The default boost factor is 2.
{
  "keywords": ["Reece:3"]
}
​
noise_cancellation
boolean
default:"false"
Toggles noise filtering or suppression in the audio stream to filter out background noise.
​
ignore_button_press
boolean
default:"false"
When true, DTMF (digit) presses are ignored, disabling menu navigation or call transfers triggered by keypad input.

​
Call Settings (Body)

​
max_duration
integer
default:"30"
When the call starts, a timer is set for the max_duration minutes. At the end of that timer, if the call is still active it will be automatically ended.Example Values: 20, 2
​
webhook
string
When the call ends, we’ll send the call details in a POST request to the URL you specify here.The request body will match the response from the GET /v1/calls/:call_id endpoint.
​
webhook_events
string[]
Specify which events you want to stream to the webhook, during the call.Options:
  • queue
  • call
  • latency
  • webhook
  • tool
  • dynamic_data
  • citations (Sent separately, Enterprise only)
Example payloads:
// ex 1
{
  "message": "Call enqueued",
  "call_id": "12345678-1234-1234-1234-123456789abc",
  "category": "queue",
  "log_level": "info"
}
​
analysis_schema
object
Define a JSON schema for how you want to get information about the call - information like email addresses, names, appointment times or any other type of custom data.In the webhook response or whenever you retrieve call data later, you’ll get the data you defined back under analysis.For example, if you wanted to retrieve this information from the call:
"analysis_schema": {
  "email_address": "email",
  "first_name": "string",
  "last_name": "string",
  "wants_to_book_appointment": "boolean",
  "appointment_time": "YYYY-MM-DD HH:MM:SS"
}
You would get it filled out like this in your webhook once the call completes:
"analysis": {
  "email_address": "johndoe@gmail.com",
  "first_name": "John",
  "last_name": "Doe",
  "wants_to_book_appointment": true,
  "appointment_time": "2024-01-01 12:00:00"
}
​
metadata
object
Add any additional information you want to associate with the call. This can be useful for tracking or categorizing calls.
​
summary_prompt
string
At the end of each call, a summary is generated based on the transcript - you can use this field to add extra instructions and context for how it should be summarized.For example: "Summarize the call in French instead of English."
​
analysis_prompt
string
Guides the output and provides additional instructions and clarifications for the analysis_schema.
​
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.
​
citation_schema_ids
string[]
The citation schema is an incredibly powerful tool for running post call analysis, including specific variable extractions, conditional logic, and more.You can build a citation schema here.
Note: Citation schemas are very powerful and accurate, but also are more resource intensive to run. As such, for the time being, they are an enterprise-only feature.

​
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.
{
    "status": "success",
    "message": "Successfully updated number +18584139939.",
    "updates": {
        "prompt": "(Your prompt)",
        "voice": "maya",
        "webhook": null,
        "first_sentence": "Roberta speaking, how can I help you?",
        "record": false,
        "max_duration": 30,
        "model": "base",
        //...
    }
}