Set a number's inbound call/SMS route
Create or replace (upsert) the inbound routing configuration for one owned DID. Choose how inbound calls are answered via type + config — route to an AI agent, a voicemail box, an ivr, a sip_forward endpoint, a ring_group, and more — with an optional fallback_type, business-hours gating, caller-ID allow/block filtering, a per-route recording override, and an optional per-DID inbound-SMS route. The route shape and any config URLs are safety-validated before persisting. This configures INBOUND handling only; it does not affect outbound calling. Returns the saved route with SIP passwords redacted. Scoped on the numbers resource (numbers:read or numbers:write).
Authorizations
Dashboard JWT token from Clerk
Headers
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.
1 - 255Sandbox 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.
true, false Path Parameters
The DID in E.164 (e.g. +14155550100). A leading + is optional — it is added if missing.
Body
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.
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.
Type-specific configuration (e.g. { agentId } for agent, { sipUri, sipUsername, sipPassword } for sip_forward).
Optional fallback route type used when the primary route fails.
Config for the fallback route.
Whether the route is active (default true).
Per-route recording override — off | all | inbound | outbound, or null to inherit the org default.
Required when type is ring_group — an existing ring-group id owned by this organization.
Optional per-DID inbound-SMS route — webhook | agent | auto_reply | disabled.