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

# Worked request and response samples

> Worked samples for the bring-your-own-carrier bind lifecycle: register a carrier (201), list the live bind rows, delete to take it out of rotation (204), and the 404 for an unknown carrier id.

## Worked request and response samples

Copy a request as written, substitute your own ids, and compare the response envelope. Errors follow Devotel Orbit's `{ error, ... }` envelope with the `error.code` your client branches on. The chain a carrier/SMPP integrator runs: **register → list the live bind → delete to retire it**.

### 1. Register a carrier bind

<Note>
  `POST /api/v1/messaging/smpp/carriers`
</Note>

**Request**

```json theme={null}
{
  "label": "euro-terminal-trunk",
  "type": "smpp",
  "remoteHost": "smpp.carrier-eu.example",
  "remotePort": 2775,
  "remoteSystemId": "orbit-mt",
  "remotePassword": "s3cr3t-bind",
  "bindType": "trx",
  "tlsEnabled": false,
  "scope": "all",
  "priority": 10,
  "status": "active"
}
```

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "id_smppcr_7k2m9x4vbn",
      "label": "euro-terminal-trunk",
      "type": "smpp",
      "description": null,
      "remoteHost": "smpp.carrier-eu.example",
      "remotePort": 2775,
      "remoteSystemId": "orbit-mt",
      "remotePasswordSet": true,
      "bindType": "trx",
      "tlsEnabled": false,
      "tlsVerifyCert": false,
      "httpUrl": null,
      "httpAuthType": null,
      "httpCredentialsSet": false,
      "scope": "all",
      "scopeFilter": null,
      "priority": 10,
      "status": "active",
      "lastSeenAt": null,
      "bindStatus": null,
      "createdAt": "2026-08-24T09:41:12.000Z",
      "updatedAt": "2026-08-24T09:41:12.000Z"
    },
    "meta": {
      "requestId": "req_smpp_create",
      "timestamp": "2026-08-24T09:41:12.000Z"
    }
  }
  ```
</ResponseExample>

The created row registers a BYO upstream termination carrier your outbound messaging traffic routes through while `status='active'`. Devotel reads the routing fields (`scope`, `priority` — lower wins) and reconciles the SMPP bind within about 30 seconds; once live, `GET` on this row reports the reconciler-observed `bindStatus` (`BOUND` / `UNBOUND` / `BIND_FAILED`) and `lastSeenAt`. The password you sent is never on the wire again — reads redact it to `remotePasswordSet: true`.

Most registrations on this platform connect to the **inbound** side (your SMSC binds to Orbit for MO and delivery receipts) — for that, create a **credential** (`POST /api/v1/messaging/smpp/credentials`) instead; a carrier is for *outbound* termination only.

### 2. List the live bind rows

<Note>
  `GET /api/v1/messaging/smpp/carriers`
</Note>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "id_smppcr_7k2m9x4vbn",
        "label": "euro-terminal-trunk",
        "type": "smpp",
        "remoteHost": "smpp.carrier-eu.example",
        "remotePort": 2775,
        "remoteSystemId": "orbit-mt",
        "remotePasswordSet": true,
        "bindType": "trx",
        "tlsEnabled": false,
        "tlsVerifyCert": false,
        "scope": "all",
        "scopeFilter": null,
        "priority": 10,
        "status": "active",
        "lastSeenAt": "2026-08-24T09:41:42.000Z",
        "bindStatus": "BOUND",
        "createdAt": "2026-08-24T09:41:12.000Z",
        "updatedAt": "2026-08-24T09:41:12.000Z"
      }
    ],
    "meta": {
      "requestId": "req_smpp_list",
      "timestamp": "2026-08-24T09:41:54.000Z"
    }
  }
  ```
</ResponseExample>

The list page returns `data` as an array of the full wire shape (see step 1 for every field). Rows come back in `priority` order, then newest-first within the same priority. There is no pagination envelope on this endpoint — the row set is a small per-tenant list. Filter `status='active'` client-side to find the routes currently eligible for outbound traffic.

### 3. Delete the carrier (204, hinted rebind)

<Note>
  `DELETE /api/v1/messaging/smpp/carriers/{id}`
</Note>

**Response:** `204 No Content`

Delete is a soft delete — the row stays in your tenant for the audit chain with `status='inactive'`, and routing stops sending through the carrier once the reconciler's next \~30-second tick removes the underlying connector. Retired it by mistake? Re-activate with `PATCH /api/v1/messaging/smpp/carriers/{id}` and `{"status": "active"}` — a hinted rebind, no re-registration needed.

### 4. Unknown carrier id → 404

Reading, updating, testing, or deleting an id that is not a carrier in your tenant returns the 404 error envelope:

```json 404 theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "status": 404,
    "message": "SMPP carrier not found."
  },
  "meta": {
    "requestId": "req_smpp_err",
    "timestamp": "2026-08-24T09:41:12.000Z"
  }
}
```