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.

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.

Register a Caller Name

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

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.

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.

curl "https://api.orbit.devotel.io/api/v1/numbers/num_abc123/cnam/spam-labels" \
  -H "X-API-Key: dv_live_sk_..."

{
  "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.

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.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

CNAM & Caller ID

CNAM & Caller ID

Register a Caller Name

Dispatch the Registration

CNAM Dip (carrier inquiry)

Spam Labels

Remediate Spam Labels

​CNAM & Caller ID

​Register a Caller Name

​Dispatch the Registration

​CNAM Dip (carrier inquiry)

​Spam Labels

​Remediate Spam Labels

CNAM & Caller ID

Register a Caller Name

Dispatch the Registration

CNAM Dip (carrier inquiry)

Spam Labels

Remediate Spam Labels