Skip to main content
View and manage call routes: phone numbers your customers can call to reach whoever is on call. Use these endpoints to read how a route is configured, and to change who it pages, the language it speaks to callers, and which number responders see when it calls them. List and edit call routes here. Create and delete them in the dashboard.

​
The call route object

A call route is a phone number your customers can call to reach whoever is on call, for an urgent support line or a regulator hotline.

When a call comes in we work down the route's path, ringing each level's targets in turn until someone answers, then connect them to the caller. A trailing voicemail node records a message instead. Every call raises an alert, so calls can open incidents through an alert route.

List and edit call routes here. Create and delete them in the dashboard.

​
allowed_callers
object[]
required

The numbers allowed to call this route. Only enforced when use_caller_allowlist is true.

Example:
​
created_at
string<date-time>
required
Example:

"2021-08-17T13:28:57.801578Z"

​
current_state
enum<string>
required

Where this route is in provisioning. Only an active route answers calls:

  • pending: created, and awaiting manual work from us
  • pending_regulatory_information: awaiting regulatory compliance information, collected in the dashboard
  • pending_number: compliance is settled, and we're provisioning a number
  • active: fully provisioned, and answering calls
Available options:
pending,
pending_regulatory_information,
pending_number,
active
Example:

"active"

​
custom_language
enum<string>
required

The language we speak voice prompts in, via text-to-speech

Available options:
en-US,
en-GB,
fr-FR,
es-ES,
pt-PT,
pt-BR,
de-DE,
nl-NL
Example:

"en-US"

​
id
string
required

Unique identifier for this call route

Example:

"01FCNDV6P870EA6S7TK1DSYDG0"

​
name
string
required

Name for this call route

Example:

"Regulator urgent request"

​
options
object[]
required

The phone-tree menu this route presents. Empty when callers are routed down the route's path.

Example:
​
path
object[]
required

Who we page when a call comes in. Empty when this route presents a phone-tree menu, in which case each menu option carries its own path.

Example:
​
responder_caller_id
enum<string>
required

Which number responders see when we call them:

  • route_number: this route's own number
  • oncall_number: an incident.io on-call number
Available options:
route_number,
oncall_number
Example:

"route_number"

​
updated_at
string<date-time>
required
Example:

"2021-08-17T13:28:57.801578Z"

​
use_caller_allowlist
boolean
required

Whether this route only answers calls from its allowed callers

Example:

true

​
country_code
string

The country this route's number belongs to

Example:

"US"

​
phone_number
string

The number your customers call to reach this route, once one has been provisioned

Example:

"+15551234567"

​
phone_number_type
enum<string>

The type of phone number, which determines the regulatory requirements for provisioning it

Available options:
toll_free,
mobile,
national,
local
Example:

"toll_free"