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

# Text-enable a number with hosted messaging

> Enable SMS on a landline, toll-free, or mobile number without porting it: open a hosted-messaging order, drive the LOA sign → submit lifecycle, route inbound SMS to a webhook or inbox, and poll to active.

# Text-enable a number with hosted messaging

Hosted messaging (also called "Hosted SMS" or "text-enable") lets a number receive SMS on Orbit while its **voice service stays with the current carrier**. Instead of porting the number, you open a hosted-messaging order, sign a Letter of Authorization (LOA) authorizing the hosting carrier to overlay SMS routing, and pick where inbound messages land — a webhook URL, an inbox, or a messaging service.

This guide walks one number end-to-end: order → LOA → submit → route → activation. Use the API when the steps belong in a pipeline; the dashboard surface at **Numbers → Hosted Messaging** mirrors the same order lifecycle.

## 1. Hosted messaging vs. a full port

A hosted-messaging order changes only how SMS on the number is routed — the voice carrier, the existing voice routing, and the carrier-of-record relationship are untouched. A full port moves voice and messaging together (see [Port a number end-to-end](/guides/port-numbers) §9 for where this choice fits in a migration).

Two hard boundaries to know up front:

* **Inbound only.** Hosted messaging delivers messages the carrier receives *on* the number. Outbound (MT) SMS on Orbit exits exclusively via the Devotel softswitch — this flow never creates an outbound path.
* **Voice never moves.** If you later want voice + SMS on Orbit, port the number instead; a hosted order is not a step toward a port.

## 2. When to choose it

Choose hosted messaging over a port when:

* **Voice must stay with the losing carrier** — a PBX contract, a bundled plan, or a carrier you are contractually locked to.
* **The number is not voice-portable** — some rate centers and country rules block ports while still allowing SMS hosting.
* **The number is a landline or toll-free you only need for messaging** — common for support lines and hotlines.

If you will eventually port number and voice together, skip hosting and run the port — a port supersedes a hosted order on the same number.

## 3. Prerequisites

Before opening an order:

* **API key with the `numbers:write` scope** for create/sign/submit/route/cancel; reads (`list`, `get`) need `numbers:read`.
* **The number in E.164 format** — `+14155550123`, not a national format.
* **Number class**: `landline`, `tollfree`, or `mobile`.
* **An inbound route target** — an `https://` webhook URL, an inbox id, or a messaging-service id. The route can be changed until the order activates.
* **LOA signer details** — the full legal name and email of the party authorized on the carrier-of-record account.

## 4. Open the order

`POST /api/v1/numbers/hosted-messaging` creates the order in `draft`. Provide the number, the carrier of record, the number class, and the initial inbound route. `businessName` is optional but recommended — carriers match the LOA against the account holder name.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155550123",
    "voiceCarrier": "AT&T",
    "numberType": "landline",
    "businessName": "Acme Inc",
    "inboundRoute": {
      "type": "webhook",
      "target": "https://hooks.example.com/inbound-sms"
    }
  }'
```

```json theme={null}
{
  "data": {
    "id": "hostedMessagingOrder_abc123",
    "phoneNumber": "+14155550123",
    "voiceCarrier": "AT&T",
    "numberType": "landline",
    "status": "draft",
    "inboundRoute": {
      "type": "webhook",
      "target": "https://hooks.example.com/inbound-sms"
    },
    "createdAt": "2026-08-24T10:15:00.000Z"
  }
}
```

A second in-flight order for the same number returns `409` — resolve the existing order (complete, reject, or cancel it) before opening a new one. Cancel any order before a terminal state with `DELETE /api/v1/numbers/hosted-messaging/{id}`.

## 5. LOA lifecycle — sign, then submit

The LOA authorizes the hosting carrier to add SMS routing to the number. Sign it in-platform (`draft → loa_signed`), then submit it to the carrier (`loa_signed → submitted`). Submitting before signing is rejected.

```bash theme={null}
# 1. Record the in-platform signature acknowledgement
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/hostedMessagingOrder_abc123/loa/sign \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "signerName": "Jane Doe",
    "signerEmail": "jane@acme.com",
    "acknowledgement": "I am authorized to text-enable this number on behalf of the account holder.",
    "loaFileUrl": "https://storage.googleapis.com/orbit-loas/acme/hosted-loa.pdf"
  }'

# 2. Forward the signed order to the hosting carrier
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/hostedMessagingOrder_abc123/submit \
  -H "X-API-Key: dv_live_sk_..."
```

`loaFileUrl` is optional — omit it if ops attaches the LOA artefact out-of-band. The acknowledgement text and signer identity are *your* organization's authorization record; capture the exact wording the signer accepted so it holds up in a dispute. Signing does not notify the carrier — that buffer lets you revoke (cancel) before submission, the same deliberate break as the [porting LOA flow](/guides/port-numbers#4-loa-lifecycle-upload-sign-submit).

## 6. Set the inbound route

Inbound SMS on the hosted number delivers to the route stored on the order. Change it while the order is `draft`, `loa_signed`, or `submitted`:

```bash theme={null}
curl -X PATCH https://api.orbit.devotel.io/api/v1/numbers/hosted-messaging/hostedMessagingOrder_abc123/route \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "inboundRoute": {
      "type": "inbox",
      "target": "inbox_01HZY8Q7"
    }
  }'
```

Route types:

| `type`              | `target`                                                             |
| ------------------- | -------------------------------------------------------------------- |
| `webhook`           | An `https://` URL Orbit POSTs the inbound message to.                |
| `inbox`             | An inbox id — the message lands in the shared inbox.                 |
| `messaging_service` | A messaging-service id — the message follows that service's routing. |

Once the order is `active`, the route locks — open a new order to change live routing. A `rejected` or `cancelled` order cannot be edited. This lock is deliberate: it keeps the carrier-side hosting config and your delivery target in lock-step.

## 7. Track the order to active

Poll `GET /api/v1/numbers/hosted-messaging/{id}` (or `GET .../hosted-messaging` for the full list) and read `status`:

| `status`     | Meaning                                                       | Next step                                         |
| ------------ | ------------------------------------------------------------- | ------------------------------------------------- |
| `draft`      | Created; no signed LOA yet.                                   | Sign the LOA.                                     |
| `loa_signed` | Signature recorded; carrier not notified.                     | Submit to the carrier.                            |
| `submitted`  | Carrier is verifying ownership.                               | Wait for `active`; respond to carrier follow-ups. |
| `active`     | SMS hosting confirmed — inbound SMS delivers to your route.   | Wire/normalize the inbound path (next step).      |
| `rejected`   | Carrier or ops refused the order; `rejectionReason` explains. | Fix the cause and open a new order.               |
| `cancelled`  | You stopped the order before activation.                      | Nothing further.                                  |

`active`, `rejected`, and `cancelled` are terminal — every other status has a next action for you.

## 8. Wire inbound webhooks

If the route type is `webhook`, treat it like any other inbound-message sink: receive the `POST`, verify the signature, dedupe on the message id, and return `2xx` fast. Follow [Webhook consumer](/guides/webhook-consumer) for the receiver pattern and [Webhook security](/webhooks/security) for signature verification. If the route is an inbox or messaging service, inbound messages surface there directly.

## 9. Troubleshooting

* **Carrier rejects the LOA (`status: rejected`).** Read `rejectionReason` on the order and fix the LOA content — mismatched account-holder name, a `businessName` that does not match the billing record, or a signer who is not authorized on the account. Cancel the dead order if needed and open a fresh one with corrected data.
* **Inbound SMS not arriving after `active`.** Check the route: webhook targets must be reachable `https` endpoints returning `2xx`; inbox/messaging-service targets must be valid ids. Until the order is `active` the carrier is not yet hosting, so no inbound traffic is expected.
* **Second order refused with `409`.** An in-flight order already exists for that number — the hosting carrier only accepts one order per number. Find it via `GET .../hosted-messaging` and either wait it out or cancel it, then recreate.
* **Port conflict.** If you decide to port the number after all, cancel the hosted order first — a full port supersedes the hosting arrangement, and running both in flight confuses the carrier.
* **Route locked.** You are seeing `409` on `route` after `active` — that is by design. Open a new order to change live routing.

The full-order checklist: verify E.164 + number class → open order → sign LOA → submit → poll to `active` → verify inbound → done.

## See Also

* [Port a number end-to-end](/guides/port-numbers) — full voice + SMS migration when hosting is the wrong tool.
* [Number Porting](/numbers/porting) — endpoint-by-endpoint porting page.
* [Numbers API Reference](/api-reference/numbers) — full request/response schemas for hosted messaging and porting.
* [Webhook consumer](/guides/webhook-consumer) — receiver pattern for `webhook` inbound routes.
* [Webhook events](/webhooks/events) — inbound message event catalog.