Skip to content

Create an inbound routing rule

POST
/voice/inbound-routing/rules

Decide where calls on one number go.

THIS CHANGES WHAT HAPPENS TO REAL CALLERS as soon as it is active. A rule with a lower priority than an existing one takes precedence over it, so creating a rule can silently retire the one that was working.

target_type and ring_strategy are closed to voice’s own sets. org_id is absent from the body and pinned from the key.

Authorizations

Parameters

Header Parameters

X-Target-Org-Id
Any of:
string

Request Body required

A rule deciding where an inbound call on one number goes.

org_id is absent on purpose - pinned from the key by the router. Rules are evaluated by ascending priority; the first whose match_conditions hold wins.

object
is_active
boolean
default: true
match_conditions

{"always": true} or a {"schedule": {...}} block with days, start_time/end_time as HH:MM, and an IANA timezone.

object
key
additional properties
any
name
Any of:
string
phone_number
required

The number this rule applies to.

string
>= 1 characters
priority

Lower wins. Ties are resolved arbitrarily.

integer
default: 100
queue_max_wait_seconds
Any of:
integer
ring_strategy
string
default: single
Allowed values: single round_robin
target_id
Any of:
string
target_type
required
string
Allowed values: ai_agent department extension voicemail

Responses

201

Successful Response

object
data
required

One voice object - a collection, an agent, a route, a chat.

Open-shaped: voice adds fields to these bodies on its own release cadence and a dropped-or-added key must not be a 500 in this service.

object
key
additional properties
any
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
notes
Any of:
Array<string>
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer
total_available
Any of:
integer
total_is_lower_bound
Any of:
boolean

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string