Skip to main content

​
Number applications

An application is a named routing container for your DIDs: a friendly label plus the inbound handler configuration you want a group of numbers to share — an IVR flow’s entry webhook, your own webhook endpoint, a SIP trunk address, or a dialer queue’s inbound handler. You bind one or many DIDs to the application, and every bound DID inherits its routing config. To move a number’s routing — or hand it between sub-account applications — you re-bind it; no re-provisioning, no re-porting. This mirrors the classic Twilio Application model white-label and reseller flows rely on: point a portfolio of DIDs at one application, and manage the routing of the whole set by editing the application instead of touching each DID. Reads need the numbers:read scope and any of the owner, admin, developer, or viewer roles. Writes (create/edit/delete/bind/unbind) need the numbers:write scope and owner, admin, or developer. Every bind is org-ownership checked, and an application never creates an outbound path — inbound routing only; outbound voice and SMS always exit through Orbit’s own network. The API reference is at Numbers. The dashboard surface at Numbers → Applications puts the same lifecycle in the UI.

​
1. Prerequisites

Before your first call:
  • An API key with numbers:read (for reads) or numbers:write (for writes). See Authentication.
  • A routing target to point the application at — your IVR flow’s entry URL, your own HTTPS webhook, or a SIP trunk address. The application stores these as handler URLs, so the target must be reachable over HTTPS.
  • DIDs owned by your organization, in E.164 format (+14155550100). Bind rejects numbers your org does not own, including numbers owned by a sibling sub-account, with a 404.

​
2. What an application binding is

An application record holds four things: A DID is bound to at most one application at a time. Binding a DID that is bound elsewhere atomically moves it — the prior application loses the number in the same transaction — so a re-bind is the single-call routing migration. Routing fields are inbound handlers only: the URLs tell Orbit where to dispatch an arriving call, SMS, or status event; nothing in an application opens an outbound path. Applications live in your organization’s own settings. Caps: 200 applications per organization and 5,000 bound DIDs per application.

​
3. Manage applications (CRUD)

All endpoints live under /api/v1/numbers/applications. Responses carry the record under data and a meta.request_id for support correlation. Create:
Returns 201 with the new record, including the id you pass to every later call. List:
Read one:
Edit — patch any of friendlyName, description, routing. At least one field is required; omitted fields are untouched, and a missing routing field removes that handler:
Delete:
Delete refuses while DIDs are still bound — see the failure section below.

​
4. Bind and unbind a DID

Bind:
Bind is idempotent: repeating the call for a DID already bound to this application succeeds without duplicating the entry. If the DID is bound to a different application, the move happens atomically — the old application drops it in the same transaction — so no orphan routing window ever exists between the move’s two halves. Unbind:
Unbind is a no-op when the number is not bound, and it never touches the DID’s provisioning — it removes only the routing/ownership link.

​
5. Read bindings for a DID

To answer “which application owns this number?”, list applications and find the one whose boundNumbers contains the DID:
Inbound routing resolves the same way: when a call or SMS arrives on a bound DID, the platform looks up its application, then dispatches to the application’s voiceUrl / smsUrl / statusCallbackUrl. A DID bound to no application keeps whatever direct per-number routing you configured elsewhere (see Assign and reassign numbers).

​
6. Common patterns

  • One application per campaign entrypoint. Campaign trackable numbers all inherit the same inbound IVR entrypoint; rotate the campaign by editing the application’s voiceUrl once, not by re-pointing every DID.
  • One application per IVR flow + number pool. Pair an IVR flow with its pool of DIDs; draining a pool into a new flow is one PATCH on the application, or a per-DID re-bind to the new flow’s application.
  • Sub-account handover (reseller flows). Re-bind the DIDs from the old application’s id to the new one; ownership and routing migrate in a single bind call per DID, upstream provisioning untouched.
  • Failover to a backup binding. Keep a standby application with a degraded route (simple webhook, voicemail greeting). When the primary handler degrades, re-bind traffic by re-calling bind against the standby — then re-bind back after recovery.

​
7. Failure handling

An application delete can never orphan a routing link: the delete is refused while any binding survives, so inbound calls never land on a deleted container. Conversely, re-binding never 409s on a “already bound elsewhere” DID — the move is the supported way to migrate.

​
Next steps