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)
Section titled “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.
Buying numbers
Section titled “Buying numbers”Search the inventory and buy numbers straight from the API (numbers:read to browse, numbers:write to buy):
| Method · Path | Purpose |
|---|---|
GET /v1/did-orders/countries | Countries numbers can be bought in. |
GET /v1/did-orders/area-codes?country=US&type=geographic | Area codes in a country. type: geographic, national, mobile, tollfree. |
GET /v1/did-orders/search?country=US&area_code=212 | Numbers available now, each with its price (filter by state, zip or npa_nxx too). |
POST /v1/did-orders | Buy up to 20 picked numbers: { items: [{ offer }] }, each offer exactly as search returned it. |
GET /v1/did-orders/orders, /{id} | Your orders, newest first. |
DELETE /v1/did-orders/numbers/{e164} | Release a number. It stays routable through the period already paid for, then drops. |
The price you see is the most you pay. A buy re-prices the number at that moment and refuses if the fresh price is above what search showed you, so a price change between browsing and buying can never surprise you. An offer older than four hours is refused as offer_expired; search again. Each item in a multi-number order gets its own outcome, so one unavailable number doesn’t fail the rest. Bought numbers appear under /v1/numbers ready to route. Numbers can’t be bought on a trial account.
GET /v1/numbers/groups counts your numbers by status, country and type, for an inventory screen.
Extensions (internal short codes)
Section titled “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
Section titled “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 | ✅ | ✅ |
Business hours on a number
Section titled “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 toclosed_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
Section titled “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 PresenceEngine alongside account- and user-level ceilings and rate rules.
Caller-ID on inbound
Section titled “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
Section titled “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.