Numbers & Extensions

Numbers are how calls enter SIP.IO. There are two kinds: DIDs (external inbound numbers) and extensions (internal short codes). Both resolve to a route target, the consistent way every object says “send the call here next.”

DIDs (inbound numbers)

A did is an external number in E.164 form (normalized, no +). Each DID points at exactly one route target:

{
  "id": "did_01j3sarpfcz8gdnnabykstr6fw", "account_id": "acc_01jf18ah3jeb5w6dfp27sgjsbt",
  "e164": "12025550123",
  "label": "Main line",
  "status": "active",
  "dest_kind": "flow", "dest_id": "flow_01jzqwjn803wtnhc445bvjenzc",
  "max_channels": 10,
  "fax_mode": "voice",
  "allow_anonymous": 1
}

Field	Purpose
e164	The number (normalized, no +). Unique across the platform.
status	active / disabled / virtual.
dest_kind / dest_id / dest_xform	The route target: where calls to this number go.
max_channels	Per-DID concurrency cap (a CAC dimension).
fax_mode	voice / t38 / passthrough.
allow_anonymous	Whether to accept calls with no/blocked caller-ID.
schedule_id + closed_dest_* / holiday_dest_*	Attached business hours.

When an inbound call arrives, the routing brain matches the DID, applies concurrency control and any attached business hours, then hands the call to the route target, most often a call flow.

Extensions (internal short codes)

An extension is an internal dialable code (ext-to-ext, feature codes). Same route-target model, scoped to the account:

{ "id": "ext_01j35sg7ss05vztd33pbd18f1h", "account_id": "acc_01jf18ah3jeb5w6dfp27sgjsbt", "digits": "1001",
  "dest_kind": "user", "dest_id": "us_01jatt0336xwzg2zbf3q9pyfm5", "status": "active" }

Extensions are matched only for authenticated callers (a registered device dialing within its account). They can also carry attached business hours.

Route targets

The route target is the trio used everywhere a call can go next:

Part	Meaning
dest_kind	The typed kind of destination.
dest_id	The id within the table implied by dest_kind.
dest_xform	Small JSON {var: val} applied on this hop (passed into the flow as variables).

Valid dest_kind values:

dest_kind	Sends the call to	DID	Extension
flow	A published call flow	✅	✅
user	A user’s registered device(s)	✅	✅
extension	Another extension	✅	❌
ring_group	A ring group	✅	✅
queue	An ACD queue	✅	✅
voicemail	A voicemail box	✅	✅
conference	A conference room	✅	✅
forward	An external call forward	✅	✅
trunk	A customer PBX, via receive-on-PBX	✅	❌
feature	A feature code	❌	✅
hangup	Reject the call	✅	✅

When to use a flow vs. a direct target

Point a number directly at a queue/ring_group/voicemail/etc. for simple routing: the platform synthesizes a one-node flow and even chains the destination’s configured exits. Use dest_kind: "flow" when you need branching (menus, time conditions, conditions, HTTP lookups).

Business hours on a number

Any DID or extension can have a schedule attached directly, so that being closed or on a holiday overrides its route target:

{
  "id": "did_01j3sarpfcz8gdnnabykstr6fw", "e164": "12025550123",
  "dest_kind": "flow", "dest_id": "flow_01jzqwjn803wtnhc445bvjenzc",
  "schedule_id": "sch_01j0jvpe0wzc6g05bktfew0xyx",
  "closed_dest_kind": "voicemail", "closed_dest_id": "vm_01jg8asp59ps9rtt7azhrhvcre",
  "holiday_dest_kind": "flow", "holiday_dest_id": "flow_01jzqbs3hn9rb3sp06ypecjn0t"
}

• In hours → the normal dest_kind/dest_id.
• Closed → closed_dest_*.
• Holiday → holiday_dest_*, falling back to closed_dest_* if not set.
• No schedule, or any config error → fail open to the normal destination (a call is never stranded on a config mistake).

This is the same “hours on the object” model used by queues and ring groups. It’s evaluated inline at routing time, before the normal destination.

Per-number concurrency

max_channels caps concurrent calls on a single DID, useful for a number you don’t want flooded, or for a tenant reselling capacity per number. It’s one dimension of Concurrency Control, enforced atomically in the account’s PresenceDO alongside account- and user-level ceilings and rate rules.

Caller-ID on inbound

The inbound caller’s number is normalized (and run through any inbound_cid number transforms) and exposed to the flow as the variable caller_cid, so you can branch on it, look it up over HTTP, or present it to an agent.

Outbound

Outbound calls (an authenticated device dialing a PSTN number) are routed by outbound routes to a trunk or the wholesale carrier, with number and caller-ID transforms applied along the way. See Outbound & Trunking.