> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Number assignments, applications, and routing

> Understand the difference between assigning a DID, configuring its inbound route, binding it to a number application, and attaching it to a messaging service.

# 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:

```bash theme={null}
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](/numbers/overview#configure-routing). For the portal walkthrough, bulk assignment, and clearing a route, see [Assign and reassign numbers](/guides/number-assignments). 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](/guides/buy-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](/guides/number-applications) 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](/guides/routing-rules) and [inbound number routing](/guides/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](/guides/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](/guides/number-assignments) — route one or many DIDs, inspect existing destinations, and clear or replace a route.
* [Number applications](/guides/number-applications) — create routing containers, edit handler URLs, bind or unbind DIDs, and handle limits and errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.