Skip to main content
PUT
Set a number's inbound call/SMS route

Authorizations

Authorization
string
header
required

Dashboard JWT token from Clerk

Headers

Idempotency-Key
string

Stripe-style idempotency token. Pass a stable, client-generated value (1-255 chars) to dedupe retries on transient timeouts. The same key+credential+path replays the original response for 24h on 2xx (5min on 4xx, 30s on 5xx). Returns 409 if a concurrent request with the same key is already in flight; replayed responses include the Idempotency-Replay: true response header.

Required string length: 1 - 255
X-Test-Mode
enum<string>

Sandbox opt-in for Clerk-session-authenticated requests. Set to true to route the call through the test-mode pipeline: no real provider delivery, no credits deducted, response meta.test_mode: true. Ignored for live API keys (dv_live_sk_*) — server-to-server clients must use a test-prefixed key (dv_test_sk_*) to exercise sandbox. Test-prefixed keys unconditionally enable sandbox regardless of this header.

Available options:
true,
false

Path Parameters

phoneNumber
string
required

The DID in E.164 (e.g. +14155550100). A leading + is optional — it is added if missing.

Body

application/json

The inbound route to persist. type + config are required and validated together by the handler.

The inbound route to persist. type + config are required and validated together by the handler.

type
string

Primary route type — one of agent, softphone_user, softphone_register, ivr, voicemail, queue, sip_forward, transfer, conference, decline, ring_group, shared_line, dispatch_to_voicemail_box, or a webhook (voiceUrl) route.

config
object

Type-specific configuration (e.g. { agentId } for agent, { sipUri, sipUsername, sipPassword } for sip_forward).

fallback_type
string | null

Optional fallback route type used when the primary route fails.

fallback_config
object | null

Config for the fallback route.

active
boolean

Whether the route is active (default true).

recording_mode
string | null

Per-route recording override — off | all | inbound | outbound, or null to inherit the org default.

ring_group_id
string | null

Required when type is ring_group — an existing ring-group id owned by this organization.

sms_route_type
string | null

Optional per-DID inbound-SMS route — webhook | agent | auto_reply | disabled.

Response

The saved inbound route (SIP passwords redacted).

The saved inbound route (SIP passwords redacted).

data
object

The persisted inbound route record.

meta
object