Skip to content

Create a routing automation

POST
/v1/numbers/{number}/automations
curl --request POST \
--url https://api.caller9.app/v1/numbers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/automations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "action": "route_studio", "dest_studio_guid": "example", "dest_trunk_guid": "example", "forward_dest_type": "sip", "forward_sip_address": "example", "forward_phone_number": "example", "label": "example", "days_mask": 1, "trigger_minute": 1, "timezone": "America/Chicago", "enabled": true }'

Creates a recurring automation that, at trigger_minute on the selected days (in timezone), routes the number to a studio (route_studio), a forward destination (route_forward), or a SIP trunk (route_trunk) — replacing whatever routing the number had, exactly like the manual routing endpoints. “Route to Studio B 9am–5pm” is two automations. Premium and Enterprise plans only (409 plan_limit with limit: did_scheduling, or call_forwarding for route_forward). Requires a full-access key.

number
required
string format: uuid

Phone number ID (UUID), not the phone number itself.

Media typeapplication/json
object
action
required
string
Allowed values: route_studio route_forward route_trunk
dest_studio_guid

Required for route_studio. A studio in the same organization.

string
<= 255 characters
dest_trunk_guid

Required for route_trunk. A SIP trunk in the same organization.

string
<= 255 characters
forward_dest_type

Required for route_forward.

string | null
Allowed values: sip phone
forward_sip_address

Required when forward_dest_type is sip. Normalized like a number forward’s sip_address.

string | null
<= 255 characters
forward_phone_number

Required when forward_dest_type is phone. Valid US/Canadian number; stored as E.164.

string | null
<= 32 characters
label

Free-text label. Defaults to empty.

string
<= 120 characters
days_mask
required

Days of week the automation fires, as a bitmask in timezone (bit 0 = Sunday … bit 6 = Saturday).

integer
>= 1 <= 127
trigger_minute
required

Minute of the day (local to timezone) the automation fires, e.g. 540 = 09:00.

integer
<= 1439
timezone
required

IANA timezone name.

string
<= 64 characters

Example

America/Chicago
enabled
boolean
default: true

The created automation.

Media typeapplication/json
object
automation
required

A recurring routing automation for a number. Exactly one destination is set, matching action: dest_studio_guid (route_studio), dest_trunk_guid (route_trunk), or the forward_* fields (route_forward).

object
guid
required
string
action
required
string
Allowed values: route_studio route_forward route_trunk
number_guid
required
string
dest_studio_guid
required
string | null
dest_trunk_guid
required
string | null
forward_dest_type
required
string | null
Allowed values: sip phone
forward_sip_address
required
string | null
forward_phone_number
required
string | null
label
required
string
days_mask
required

Bitmask of days (bit 0 = Sunday … bit 6 = Saturday).

integer
>= 1 <= 127
trigger_minute
required
integer
<= 1439
timezone
required
string
enabled
required
integer
Allowed values: 0 1
last_fired_at

When the automation last fired. Included on create/update responses only.

string | null format: date-time
studio_guid

Always null for number automations. Included on create/update responses only.

null
action_value

Always null for number automations. Included on create/update responses only.

null
created_at
required
string format: date-time
updated_at
required
string format: date-time

Example

{
"automation": {
"action": "route_studio",
"forward_dest_type": "sip",
"enabled": 0
}
}

The request was invalid.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

The key isn’t allowed to do this (e.g. a read-only key making a change).

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Not found, or belongs to another organization.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}

Blocked by the organization’s plan.

Media typeapplication/json
object
error
required
string
Allowed value: plan_limit
limit
required

Which cap was hit, e.g. studios, numbers, ai_screening, trunk_channels.

string
message
required
string

Example

{
"error": "plan_limit"
}

Too many requests for this API key. Retry after Retry-After seconds.

Media typeapplication/json
object
error
required

Human-readable error message.

string
code

Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).

string

Example generated

{
"error": "example",
"code": "example"
}
Retry-After
integer

Seconds until the rate-limit window resets.