Pick the right inbound routing for a DID

​

1. What the routing config is

• type — the routing decision: run an IVR flow, drop into a queue, ring a softphone, take a voicemail, drop the call, and so on. The full enum is in section 2.
• config — a type-specific object. Each type accepts exactly one shape and validates it at write time, so a wrong-shaped config answers 422 instead of breaking mid-call. ivr takes { flowId }; queue takes { queueId }; a department mailbox takes { boxId }; decline takes no config at all.

• fallback_type + fallback_config — a depth-1 fallback destination, used when the primary route fails (queue has nobody available, webhook URL times out). The fallback accepts the same type set, but only agent, softphone_user, softphone_register, voicemail, ivr, queue, and sip_forward have fallback editors in the dashboard.
• business_hours — a schedule gate in front of the route. Outside the window, the route behaves as if no schedule matched, and the caller follows your primary path (or the fallback when hours complement it).
• caller_id_filter — allow/block/VIP lists matched on the inbound caller number. A blocked caller short-circuits before the route fires; a VIP always passes.
• recording_mode — per-route override of the org recording default: off, all, inbound, or outbound.
• sms_route_type + sms_route_config — an independent per-DID SMS termination (webhook, agent, auto_reply, or disabled). Voice and SMS on the same DID are separate settings on the same row; the voice route never blocks the SMS route.
• active — flip off to deactivate the route without deleting it. An inactive DID falls through to your org default inbound handling.

​

2. The full route type enum

​

3. The three writing paths

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/+14155550123/routing" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "queue",
    "config": { "queueId": "queue_01h..." },
    "fallback_type": "voicemail",
    "fallback_config": { "maxDurationSec": 120 },
    "business_hours": {
      "days": ["mon", "tue", "wed", "thu", "fri"],
      "start": "09:00",
      "end": "17:00",
      "timezone": "America/New_York"
    }
  }'

​

4. Decision: which type for which scenario

​

5. Companion routing — patterns, keywords, and messaging

• DNIS pattern routing — one target_type + target_config rule per a block of DIDs, matching by E.164 prefix or regex. Per-DID routing (this page) always wins: a specific DID with its own entry beats the pattern, so use patterns as the fallback layer under your explicit numbers.
• Keyword auto-reply rules — on the SMS/WhatsApp/RCS/Viber side, a rule fires before a human sees the inbox: reply, opt-in/out, hand to an agent, or trigger a flow. Voice routing is untouched by it; message routing picks up where [sms_route_type](#1-what-the-routing-config-is) terminates.
• Hosted messaging — when a DID is provisioned for messaging at hosting, the inbound SMS destination is decided at order time. The sms_route_type sibling on this row re-points it after activation, per DID.

​

6. Verify with the simulator before you attach

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/ivr-flows/ivr_01h.../simulate" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "turns": [{ "digits": "1" }], "source": "published", "max_steps": 50 }'

​

7. Common mistakes

• Attaching a draft IVR. The route stores the flow’s id; the gateway resolves the published head at call time. If you wrote the row before you published, the caller hears whatever was last published — sometimes the empty stub, sometimes an older version. Publish, simulate source: "published", then attach.
• Missing flowId on ivr, missing queueId on queue, missing boxId on dispatch_to_voicemail_box. Strict-shape validation rejects the write with 422 and a message naming the required field — but the Numbers tab that echoes a saved row with an empty config section wrote it before this validation existed. If an existing DID answers the wrong destination, re-save the route with the config filled in.
• Sending the redacted sip_forward password. Readback returns sipPassword: "***". If you POST that literal *** back without retyping the password, the API preserves the stored one — but pasting *** into a brand-new route stores a literal *** as the password. Retype it on change.
• Setting the fallback to a type the dashboard can’t configure. The fallback panel only edits agent, softphone_user, softphone_register, voicemail, ivr, queue, and sip_forward. Richer primary-only types (transfer, conference, decline, ring_group, dispatch_to_voicemail_box, shared_line, webhook) save an empty config when picked as a fallback from an older dashboard — a 422 on the types that need a target. Pick the fallback from the supported subset.
• Putting the ring-group identity in config. ring_group accepts {} — the group id lives in the sibling ring_group_id field on the body, not inside config. A config.ringGroupId key is a strict-mode 422.
• Two routes for one DID. There is one row per DID — a second PUT replaces the first. If you need two destinations, use fallback_type; if you need a menu in front, put both behind an ivr flow and route inside it.
• business_hours written with the wrong key spelling. The strict schema accepts only { days, start, end, timezone } (numeric or "mon"..-style day names) or the per-day { mon: { open, close }, ... } shape. A mis-typed key (startTime, tz) now answers 422 at write — before this, it silently meant “no schedule”. If a schedule looks inactive, re-check which shape you saved.
• Keyword rules vs auto_reply. A bulk sms_route_type: "auto_reply" replies one fixed body to every inbound text on the DID; a keyword rule replies only when its keyword matches. Don’t set auto_reply on a number that also runs keyword rules — the per-DID reply fires before rules evaluate.