Skip to main content
POST
Add Phone Number
Set inbound_workflow_id to bind incoming calls on this number to a specific agent — Bandwidth Agent Builder will register the inbound webhook with the provider and the response will include a provider_sync block reporting the result. Omit it to add the number for outbound use only. The (provider, account_id, address) tuple must be globally unique across all Bandwidth Agent Builder organizations, since inbound dispatch keys on it. Attempting to add a number that another organization already owns returns 409.

Authorizations

Authorization
string
header
required

Bandwidth Labs OAuth access token. Uses the user's selected workspace; the workspace header is not required. Do not also send an API key. Bearer-only operations may additionally require the Labs super_user role.

Headers

X-VOAI-ORGANIZATION-ID
string | null

Required with X-BW-LABS-AGENTS-API-KEY: the positive local workspace ID to access. The key owner must be a current member. Missing or invalid IDs return 400; non-member workspaces return 403. Not required for bearer authentication, which uses the user's selected workspace.

Path Parameters

config_id
integer
required

Body

application/json
address
string
required
Required string length: 1 - 255
country_code
string | null
Required string length: 2
extra_metadata
Extra Metadata · object
inbound_workflow_id
integer | null
is_active
boolean
default:true
is_default_caller_id
boolean
default:false
label
string | null
Maximum string length: 64

Response

Successful Response

address
string
required
address_normalized
string
required
address_type
string
required
created_at
string<date-time>
required
extra_metadata
Extra Metadata · object
required
id
integer
required
is_active
boolean
required
is_default_caller_id
boolean
required
telephony_configuration_id
integer
required
updated_at
string<date-time>
required
country_code
string | null
inbound_workflow_id
integer | null
inbound_workflow_name
string | null
label
string | null
provider_sync
ProviderSyncStatus · object | null