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

# CNAM & Caller ID

> Register the branded caller name shown on outbound calls, dip the carrier database, and remediate spam labels

# CNAM & Caller ID

Register the branded outbound **Calling Name (CNAM)** displayed on the recipient's handset for each of your numbers, query what a carrier currently has registered, and remediate "Spam Likely" / "Scam Likely" labels that hurt your answer rate.

Every verb is gated by org ownership — a sibling subaccount sharing your tenant schema cannot read or mutate another subaccount's registration.

<Note>
  **Invariant #45.** CNAM is an outbound caller-identity signal, so the authoritative LIDB write runs only on the Devotel wholesale softswitch (the carrier of record). The API layer **captures and enqueues** the desired name — it never wires a Telnyx/DIDWW CNAM write directly. Captured registrations stay `pending` until dispatched.
</Note>

## Register a Caller Name

```bash theme={null}
# Capture the desired display name (status: "pending")
curl -X PUT https://api.orbit.devotel.io/api/v1/numbers/num_abc123/cnam \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "display_name": "ACME SUPPORT" }'

# Read the current registration
curl "https://api.orbit.devotel.io/api/v1/numbers/num_abc123/cnam" \
  -H "X-API-Key: dv_live_sk_..."

# Remove it
curl -X DELETE https://api.orbit.devotel.io/api/v1/numbers/num_abc123/cnam \
  -H "X-API-Key: dv_live_sk_..."
```

## Dispatch the Registration

Hand the captured name to the Devotel wholesale CNAM/LIDB provisioning queue. This advances the registration `pending`/`failed` → `submitted` and stamps `submitted_at`. Until you dispatch, the name never appears on a handset.

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

Returns `404` when there is no captured registration, and `409` when it is already `submitted`/`active`.

## CNAM Dip (carrier inquiry)

Query what display name a carrier currently has registered for one of your numbers — independent of your locally-captured registration.

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

The dip target (the Devotel wholesale CNAM/LIDB database) is not yet contracted, so today the result is `status: "coming_soon"` with `carrier_registered_name: null` — the result echoes your local registration so you can reconcile desired-vs-carrier in one round-trip once the dip wires.

## Spam Labels

Read the cross-carrier spam-label snapshot observed on a number, with a derived severity summary. Spam labels are not yet automatically polled from carrier reputation APIs and will appear empty until this feature is released.

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

```json theme={null}
{
  "data": {
    "id": "num_abc123",
    "labels": [],
    "summary": { "total": 0, "carriers": [], "flagged": false, "worst_label": null },
    "remediation": null
  }
}
```

## Remediate Spam Labels

File a cross-carrier remediation request against an observed label set.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/num_abc123/cnam/remediate \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "carriers": ["Hiya"], "note": "Legitimate support line, not spam." }'
```

| Field      | Type             | Description                                                  |
| ---------- | ---------------- | ------------------------------------------------------------ |
| `carriers` | string\[] (≤ 50) | Optional. Defaults to every carrier that flagged the number. |
| `note`     | string (≤ 2000)  | Optional free-text context for the dispute.                  |

Returns `422` when the number is clean (nothing to remediate) and `404` when the number doesn't exist. The submission captures the request locally; the authoritative carrier dispute runs later on the Devotel wholesale side-band.