> ## 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 applications: bind DID inbound routing to IVR, webhook, or SIP targets

> Create a named application, bind DIDs to it, move a DID between applications with one re-bind, and resolve which application an inbound call routes to. Full CRUD + bind/unbind curl sequences and failure handling.

# 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](/api-reference/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](/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:

| Field          | Meaning                                                                                                                                                               |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `friendlyName` | Operator-facing label — "Sales IVR", "Reseller: Acme". 1–120 characters.                                                                                              |
| `description`  | Optional longer note, up to 2000 characters.                                                                                                                          |
| `routing`      | Inbound handler URLs: `voiceUrl` (inbound voice), `smsUrl` (inbound SMS), `statusCallbackUrl` (delivery and call events). All HTTPS-only; unset fields you leave out. |
| `boundNumbers` | The E.164 DIDs currently bound to the application.                                                                                                                    |

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

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/applications" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "friendlyName": "Sales IVR",
    "description": "Inbound routing for the sales line portfolio",
    "routing": {
      "voiceUrl": "https://ivr.example.com/sales/entry",
      "statusCallbackUrl": "https://hooks.example.com/orbit-events"
    }
  }'
```

Returns `201` with the new record, including the `id` you pass to every later call.

**List:**

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/numbers/applications" \
  -H "X-API-Key: dv_live_sk_..."
```

**Read one:**

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/numbers/applications/numberApplication_01J..." \
  -H "X-API-Key: dv_live_sk_..."
```

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

```bash theme={null}
curl -X PATCH "https://api.orbit.devotel.io/api/v1/numbers/applications/numberApplication_01J..." \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "routing": { "voiceUrl": "https://ivr.example.com/sales/v2" } }'
```

**Delete:**

```bash theme={null}
curl -X DELETE "https://api.orbit.devotel.io/api/v1/numbers/applications/numberApplication_01J..." \
  -H "X-API-Key: dv_live_sk_..."
```

Delete refuses while DIDs are still bound — see the failure section below.

## 4. Bind and unbind a DID

**Bind:**

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/applications/numberApplication_01J.../bind" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+14155550100" }'
```

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

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/applications/numberApplication_01J.../unbind" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+14155550100" }'
```

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:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/numbers/applications" \
  -H "X-API-Key: dv_live_sk_..." \
| jq '.data[] | select(.boundNumbers | index("+14155550100"))'
```

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](/guides/number-assignments)).

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

| Status | Code               | Cause and fix                                                                                                                                                          |
| ------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `404`  | `NOT_FOUND`        | Unknown application id on read/edit/delete/bind, or the DID is not owned by your org on bind. List applications, check the id, and verify the number's ownership.      |
| `409`  | `CONFLICT`         | Delete attempted while DIDs are still bound. Unbind or re-bind them, then delete.                                                                                      |
| `422`  | `VALIDATION_ERROR` | Malformed payload: non-E.164 `phoneNumber`, empty patch (supply at least one field), or a non-HTTPS routing URL. The `error.details` array names each offending field. |
| `429`  | `QUOTA_EXCEEDED`   | 200 applications per organization, or 5,000 bound numbers on one application. Delete an unused application, or spread bindings.                                        |

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

* [Assign and reassign numbers](/guides/number-assignments) — per-number routing targets (queues, IVR, voicemail, SIP) when bindings are not the right fit.
* [Buy and provision numbers](/guides/buy-numbers) — acquire the DIDs you bind.
* [API reference: Numbers](/api-reference/numbers) — full endpoint surface.