Route many inbound numbers to one queue with DNIS patterns

​

1. How matching works

• pattern_kind — prefix or regex.
• pattern — the match expression. For prefix, an E.164 prefix such as +4420 matches every dialed number that starts with it. For regex, a regular expression the dialed E.164 number must match in full, e.g. \+1(800|888|877)\d{7} for the classic US toll-free ranges. Patterns are stored and evaluated in E.164 form, so include the leading +.
• name — a label for the grid and audit log, e.g. “Support EN toll-free pool”.
• priority — an integer, lower wins. Rules at priority 100 (the default) are considered before rules at priority 500; a priority-10 carve-out beats both.
• target_type + target_config — where a matched call goes. The target types are the same set inbound routing uses: queue, ivr, agent, voicemail, sip_forward, transfer, conference, ring_group, shared_line, softphone_user, softphone_register, dispatch_to_voicemail_box, or decline. The config shape is whatever that target type takes — the same JSON body you’d put on a matching inbound route, e.g. { "queueName": "Support_EN" }.
• active — flip off to disable a rule without deleting it. Inbound calls it would have matched fall through to lower rules or your default handling.

1. A per-number override wins first. If the dialed DID has its own entry in inbound routing, that entry handles the call — no pattern is consulted. This is how you carve out one special number from a block (see section 5).
2. Among DNIS rules, the server evaluates your rules in precedence order: lowest priority number first; within the same priority, the most specific pattern (longest pattern string) first; ties broken by the oldest rule. The first rule that matches the dialed number handles the call.
3. If no rule matches, the call falls through to your organization’s default inbound handling.

• Specific beats general only within the same priority. A broad prefix like +1 at priority 10 still loses to a narrow prefix like +1800555 at priority 10, but +1 at priority 10 beats +1800555 at priority 100. Keep broad catch-alls at a high priority number (e.g. 900) so narrow rules can sit below them.
• Overlap is rejected, not silently tolerated. Creating or replacing a rule whose pattern overlaps another active rule at the same priority returns 409 — ambiguous routing is an error, not a coin flip. Layer the rules on different priorities to express “broad fallback, narrow override.”

​

2. Manage rules from the dashboard

1. Click Create rule (top right).
2. In the dialog, set Name, Pattern kind (E.164 prefix or Regex), Priority (default 100, lower wins), and the Pattern itself — prefix example +1800, regex example \+1(800|888|877)\d{7}.
3. Choose the Target type and fill Target config (JSON) with that target’s settings, e.g. { "queueName": "Support_EN" }. The same shape you’d use on the matching inbound-route type. Leave it {} for targets that need no config.
4. Leave Active on, click Create rule.

​

3. Manage rules over the API

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/dnis-routes/" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "UK London geo pool",
    "pattern_kind": "prefix",
    "pattern": "+4420",
    "priority": 100,
    "target_type": "queue",
    "target_config": { "queueName": "Support_EN" },
    "active": true
  }'

• pattern_kind — prefix or regex (required).
• pattern — E.164-form prefix (leading +, digits) or a full-match regular expression (required, max 256 chars).
• name — operator label shown in the dashboard grid (required, max 128 chars).
• priority — integer 0–100000, default 100; lower wins at match time.
• target_type — one of the inbound target types listed in section 1 (required).
• target_config — the target’s settings as a JSON object; {} when the target needs none.
• active — true by default; set false to stage a rule without enabling it.

• 422 — a field failed validation (pattern empty, priority out of range, malformed enum). The details object names the offending fields.
• 409 — the pattern overlaps an existing active rule at the same priority. Change the priority to layer the rules, or edit the existing rule instead.
• 404 — the rule id doesn’t exist for your organization (wrong id, or another tenant’s id).
• 401/403 — missing credentials, or the caller lacks an owner/admin/developer role or the voice:write scope on a write.

​

4. Test the rule with a sample call

1. Create the rule with active: false, or with the real pattern but a harmless target such as voicemail.
2. Confirm the match order with GET /api/v1/voice/dnis-routes/ — your rule should appear where you expect in the precedence ordering (server-sorted: priority ascending, then most specific within the priority).
3. Buy or pick one DID in the block and call it from a PSTN phone. The call should land on the target — the queue rings its members, the IVR plays its opening prompt, or the voicemail greeting answers.
4. If the call hits your default handling instead, check in order: does the DID’s pattern actually match (E.164 form, leading + included)? Is the rule active? Is a higher-priority or more-specific rule matching first? Does the DID itself have a per-number inbound routing entry overriding the pattern?
5. When the sample behaves, flip active to true (or point the target at the real queue) — every DID in the block now routes the same way.

​

5. Common setups

+4420   → queue Support_EN   (priority 100)
+331    → queue Support_EN   (priority 100)
+4930   → queue Support_DE   (priority 100)

pattern_kind: "regex"
pattern: "\+1(800|888|877)\d{7}"
priority: 100
target_type: "ivr"

​

6. Troubleshooting