Number assignments and applications

A DID can have several independent relationships. An assignment chooses where inbound traffic goes; a routing rule determines how traffic is handled; a messaging-service binding makes a number available to a messaging service. A number application groups DIDs under shared inbound handler URLs. These terms describe different controls, so changing one does not automatically change the others.

DID assignments

Open Numbers → Assignments to use the Assignment Portal. It lists active numbers with no inbound route (or, when you include assigned numbers, their current route) and lets you assign or reassign them in bulk. Assignment controls connect a number with the destination or service that should use it: depending on the control, that can be a user, team, queue, messaging service, or AI agent. In the Assignment Portal, inbound call destinations include AI agents, IVR flows, queues, ring groups, voicemail, SIP destinations, and webhooks. A messaging-service association is a separate binding for messaging, not an inbound voice route. Available choices depend on what you have configured and on the number’s capabilities. For example, a number without voice capability cannot carry inbound calls. The portal applies each number separately. Review the current route and confirm the change; the result reports success or failure per DID. To clear an existing route, use the clear-routing action or set the route to decline when you intentionally want to reject inbound calls. A cleared route returns the active DID to the unassigned list. decline is an explicit route, not an unassigned state. Use these organization-scoped endpoints with an API key that has numbers:read for reads or numbers:write for changes:

Method	Path	Purpose
`GET`	`/api/v1/numbers/:phoneNumber/routing`	Read the DID’s current inbound route.
`PUT`	`/api/v1/numbers/:phoneNumber/routing`	Set or replace its inbound route.
`DELETE`	`/api/v1/numbers/:phoneNumber/routing`	Clear its inbound route.

For example, route inbound calls and SMS to an agent:

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/+14155550100/routing" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "agent",
    "config": { "agentId": "agt_support" },
    "sms_route_type": "agent",
    "sms_route_config": { "agentId": "agt_support" }
  }'

The voice route and SMS route are independent settings. A voice route does not, by itself, configure inbound SMS handling. For supported route types and configuration fields, see Phone numbers: configure routing. For the portal walkthrough, bulk assignment, and clearing a route, see Assign and reassign numbers. This route API does not itself assign a number to a user or team or attach it to a messaging service; manage those relationships on their respective surfaces.

Number applications: routing containers, not number orders

Numbers → Applications manages named inbound-routing containers. Create an application when several DIDs should share the same inbound voice, SMS, or status-callback handler URLs, or when you want to move a DID between those configurations by binding it to another application. Binding does not buy, port, or provision a number. A DID can be bound to at most one number application at a time; a re-bind moves it from its previous application. Do not confuse this routing-container screen with a number order application. Buy a number directly with Buy and provision numbers when it is available for immediate purchase. Start an order/application instead when that number or market requires an application or carrier review; availability and review requirements vary by country and number type. Follow the status shown for that order:

Status	Meaning
`draft`	The application is being prepared and has not been sent for review.
`submitted`	The application has been sent for review.
`approved`	The application has passed review; provisioning may proceed.
`fulfilled`	The order has completed and the provisioned DID is available in your number inventory.

A fulfilled order produces a number in your inventory; it does not automatically assign an inbound destination, bind the number to a number application, or attach it to a messaging service. Configure each relationship you need after provisioning. The number-application endpoints are under /api/v1/numbers/applications: GET and POST the collection; GET, PATCH, and DELETE an application by :id; and POST to /:id/bind or /:id/unbind with a phoneNumber. Reads require numbers:read; changes require numbers:write. A DID must belong to your organization to bind it. See Number applications: create and bind routing containers for endpoint examples, limits, and failure responses.

Tell these controls apart

Control	What it changes	Use it for	Where to manage it
DID assignment / inbound route	The destination that receives inbound voice or SMS for one DID.	Point a number to an agent, user endpoint, IVR, queue, ring group, voicemail, SIP destination, or webhook.	Numbers → Assignments or the number’s routing details; `GET`/`PUT`/`DELETE /api/v1/numbers/:phoneNumber/routing`.
Routing rule	The behavior or decision applied while handling traffic; it may include the route target and channel-specific settings.	Change how calls or messages are directed, not who owns the DID or which numbers belong to a messaging service.	Inbound number routing; see routing rules and inbound number routing.
Number-application binding	The link between a DID and a named set of inbound handler URLs.	Share handler configuration across DIDs or move a DID between application configurations.	Numbers → Applications; `/api/v1/numbers/applications/:id/bind` and `/unbind`.
Messaging-service binding	The association between an SMS-capable number and a messaging service’s sender pool and messaging settings.	Make a number available to the service for messaging. This does not assign its voice destination or create a voice route.	Messages → SMS → Services; manage attached numbers in the service. See Messaging services console.

A messaging-service attachment is not an outbound route instruction. Outbound SMS continues through Orbit’s configured wholesale termination path; attaching a number to a service does not change that path.

Who can make changes?

DID route changes and number-application changes require an organization API key with numbers:write; reads require numbers:read. In the dashboard, Owner, Admin, or Developer roles can make these changes, while Owner, Admin, Developer, or Viewer roles can read. Submitting an order application is also a number-write action: use an authorized organization member with numbers:write (Owner, Admin, or Developer in the dashboard). Dashboard permission checks still apply, so ask an organization owner or admin if a control is unavailable to your account. Buying or submitting an order is separate from assigning a DID. Follow any market-specific information requests shown in the order workflow; changing a route or binding a messaging service does not submit an order.

Task guides

Assign and reassign numbers — route one or many DIDs, inspect existing destinations, and clear or replace a route.
Number applications — create routing containers, edit handler URLs, bind or unbind DIDs, and handle limits and errors.

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Changelog

Number assignments, applications, and routing

Number assignments and applications

DID assignments

Number applications: routing containers, not number orders

Tell these controls apart

Who can make changes?

Task guides

​Number assignments and applications

​DID assignments

​Number applications: routing containers, not number orders

​Tell these controls apart

​Who can make changes?

​Task guides

Number assignments and applications

DID assignments

Number applications: routing containers, not number orders

Tell these controls apart

Who can make changes?

Task guides