Forward a number
const url = 'https://api.caller9.app/v1/numbers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/forward';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"dest_type":"sip","sip_address":"sip:studio@pbx.example.com","phone_number":"+15551234567"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Phone number ID (UUID), not the phone number itself.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Required when dest_type is sip. Form sip:user@host[:port] (or sips:); a bare user@host gets sip: prepended.
Example
sip:studio@pbx.example.comRequired when dest_type is phone. Must be a valid US or Canadian number; stored as E.164.
Example
+15551234567Responses
Section titled “Responses”The stored forward destination.
object
A direct, unconditional forward destination for a number. Exactly one of sip_address / phone_number is set, matching dest_type.
object
Present on the PUT response; omitted when embedded in GET /v1/numbers/{number}.
Normalized SIP URI (sip:user@host).
E.164 phone number.
Example
{ "forward": { "dest_type": "sip" }}The request was invalid.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Missing, invalid, expired or revoked API key.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}The key isn’t allowed to do this (e.g. a read-only key making a change).
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Not found, or belongs to another organization.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Blocked by the organization’s plan.
object
Which cap was hit, e.g. studios, numbers, ai_screening, trunk_channels.
Example
{ "error": "plan_limit"}Too many requests for this API key. Retry after Retry-After seconds.
object
Human-readable error message.
Machine-readable code (authentication failures only, e.g. KEY_EXPIRED, RATE_LIMITED).
Example generated
{ "error": "example", "code": "example"}Headers
Section titled “Headers”Seconds until the rate-limit window resets.