Skip to main content

​
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. Labels are stamped out-of-band by a reputation poller. 
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": [{ "carrier": "Hiya", "label": "Spam Likely" }],
    "summary": { "severity": "high", "flagged_carriers": 1 },
    "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." }'
FieldTypeDescription
carriersstring[] (≤ 50)Optional. Defaults to every carrier that flagged the number.
notestring (≤ 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.