Skip to content

Forward a number

PUT
/v1/numbers/{number}/forward
curl --request PUT \
--url https://api.caller9.app/v1/numbers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/forward \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "dest_type": "sip", "sip_address": "sip:studio@pbx.example.com", "phone_number": "+15551234567" }'

Unconditionally forwards inbound calls on this number to a SIP address or a US/Canadian phone number, replacing any existing forward and clearing any studio assignment or SIP trunk routing. Premium and Enterprise plans only (409 plan_limit with limit: call_forwarding). Requires a full-access key.

number
required
string format: uuid

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

Media typeapplication/json
object
dest_type
required
string
Allowed values: sip phone
sip_address

Required when dest_type is sip. Form sip:user@host[:port] (or sips:); a bare user@host gets sip: prepended.

string
<= 255 characters

Example

sip:studio@pbx.example.com
phone_number

Required when dest_type is phone. Must be a valid US or Canadian number; stored as E.164.

string
<= 32 characters

Example

+15551234567

The stored forward destination.

Media typeapplication/json
object
forward
required

A direct, unconditional forward destination for a number. Exactly one of sip_address / phone_number is set, matching dest_type.

object
number_guid

Present on the PUT response; omitted when embedded in GET /v1/numbers/{number}.

string
dest_type
required
string
Allowed values: sip phone
sip_address
required

Normalized SIP URI (sip:user@host).

string | null
phone_number
required

E.164 phone number.

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

Example

{
"forward": {
"dest_type": "sip"
}
}

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.