Number Health & Reputation

Monitor the operational health of each number: its 10DLC warming ramp, deliverability health score, carrier-displayed reputation, usage rollups, and branded-calling answer-rate uplift. Every endpoint is a pure read of locally-persisted snapshots — no live carrier call, no outbound voice/SMS path.

Warming

Per-number 10DLC warming-tier state, so a warming-progress card can render the ramp meter.

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

Returns the current daily_cap, live current_day_count, warming_phase (initial | ramp | steady | verified), trust_score, and warming_started_at. Returns null for non-10DLC numbers. For the growth-curve forecast:

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

Returns the warming_state + warming_started_at + warming_max_daily_sms columns plus a 15-day forecast.

Health (deliverability)

The latest deliverability health snapshot — delivery rate and complaint rate — from the daily health-score scheduler.

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

This scores internal deliverability (complaint-coded message error codes). For the carrier-displayed spam label, use Reputation below.

Health trend & forecast (predictive)

The point-in-time health snapshot tells you where a number stands today; it does not tell you where it is heading. The trend endpoint answers the predictive question — is this number sliding toward a poor delivery outcome, and how soon — so you can rotate it before deliverability collapses. GET /api/v1/numbers/num_abc123/health/trend

curl "https://api.orbit.devotel.io/api/v1/numbers/num_abc123/health/trend?window=90d&bucket=week&horizon_days=14" \
  -H "X-API-Key: dv_live_sk_..."

Parameter	Values	Default	Description
`window`	`30d` \| `60d` \| `90d`	`90d`	Lookback window. A trend needs a long lens.
`bucket`	`day` \| `week`	`week`	Period granularity of the score series.
`horizon_days`	1–60	`14`	How far past the last period the forecast projects.

{
  "data": {
    "phone_number_id": "num_abc123",
    "phone_number": "+14155550100",
    "window": "90d",
    "bucket": "week",
    "points": [
      {
        "period_start": "2026-08-03T00:00:00.000Z",
        "period_end": "2026-08-10T00:00:00.000Z",
        "score": 91.0,
        "tier": "excellent",
        "sample_size": 840
      }
    ],
    "scored_periods": 12,
    "direction": "declining",
    "slope_per_day": -0.4,
    "forecast": {
      "horizon_days": 14,
      "projected_score": 48.2,
      "projected_tier": "poor",
      "slope_per_day": -0.4
    },
    "anomaly": {
      "detected": false,
      "latest_score": 80.5,
      "baseline_mean": 86.1,
      "deviation": -5.6
    },
    "min_sample_size": 50
  }
}

direction is improving, declining, or stable. Movement smaller than 0.2 score points per day counts as stable so week-to-week noise does not read as a trend.
forecast extrapolates the trend line: projected_score (clamped to 0–100) and projected_tier, mapped onto the same tier bands the point-in-time score uses. When projected_tier falls to poor or critical, that number is a rotation candidate — pair the forecast with the Closed-Loop Reputation Remediation playbook below to quarantine, replace, and retire it.
anomaly catches what a slow slope would smear away: detected: true when the latest period drops 12+ points below the mean of the periods before it — the signature of a spam flag landing between ticks.
Low-traffic periods stay honest: a period under min_sample_size outbound messages returns score: null, tier: "unknown" and is excluded from the trend fit (its sample_size is still returned so you can render the gap). With fewer than three scored periods, direction returns insufficient_data and the forecast is null — Orbit will not project a line through one or two points.

Predictive spam-likelihood scoring & remediation playbook

The trend forecast above projects a deliverability score; the spam-likelihood endpoint answers a different question — how likely is this number to draw a carrier spam label, and what to do about it before the label lands. Where the trend endpoint tracks a health trajectory, this one blends the signals carriers actually filter on into a single forward-looking risk score and pairs it with an ordered remediation playbook. Use it as the early-warning threshold: act on high/severe here, before the carrier ecosystem publishes the label you see under Reputation. GET /api/v1/numbers/:id/spam-likelihood

curl "https://api.orbit.devotel.io/api/v1/numbers/num_abc123/spam-likelihood?window=30d&horizon_days=14" \
  -H "X-API-Key: dv_live_sk_..."

Parameter	Values	Default	Description
`window`	`7d` \| `14d` \| `30d`	`30d`	Lookback window folded into the score.
`horizon_days`	1–60	`14`	Forecast horizon for the trend input.

{
  "data": {
    "phone_number_id": "num_abc123",
    "phone_number": "+14155550100",
    "window": "30d",
    "window_start": "2026-07-25T00:00:00.000Z",
    "window_end": "2026-08-25T00:00:00.000Z",
    "spam_likelihood": {
      "spam_likelihood_score": 62.4,
      "spam_likelihood_label": "high",
      "contributing_factors": {
        "failure_rate": 0.18,
        "complaint_rate": 0.11,
        "trend": "declining",
        "anomaly_detected": true,
        "failure_component": 7.2,
        "complaint_component": 40,
        "trend_component": 15,
        "anomaly_component": 5
      },
      "remediation_playbook": [
        {
          "step": 1,
          "action": "pause_outbound",
          "guidance": "Pause outbound sending from this number while the signals settle."
        },
        {
          "step": 2,
          "action": "verify_registration",
          "guidance": "Re-verify the sender's registered campaign (10DLC, toll-free verification, or free-entry form); fix any gaps."
        },
        {
          "step": 3,
          "action": "reduce_volume",
          "guidance": "Temporarily drop outbound volume until the failure and complaint rates normalise, then re-ramp gradually."
        },
        {
          "step": 4,
          "action": "warm_replacement",
          "guidance": "Warm a replacement number so inbound routes, dialer campaigns, and sender pools can migrate without a hard cutover."
        }
      ]
    },
    "trend": { "scored_periods": 27, "direction": "declining" },
    "min_sample_size": 50
  }
}

contributing_factors names which drivers pushed the risk up: the outbound failure_rate, the complaint-coded complaint_rate (carrier rejections with a spam or opt-out error code), the health trend direction, and any anomaly_detected step-change. The four *_component values sum to the score, so you can see exactly which lever to pull. remediation_playbook is the ordered set of steps to take before the label lands: pause outbound, re-verify the registered campaign, and — once the score reaches moderate or worse — reduce volume and warm a replacement. Labels band as low (< 25), moderate (< 50), high (< 75), severe (75+); a window with too little signal returns spam_likelihood_score: null with label unknown rather than a noisy small-sample number, and min_sample_size echoes the threshold. Tie to action. When the playbook returns reduce_volume, put the rest behind send gating and quiet hours: lower the campaign’s pacing cap on this number, tighten its quiet-hours window, and let warmed DIDs absorb the traffic. When the playbook returns warm_replacement, fold it into the Closed-Loop Reputation Remediation policy below — the same quarantine → replace → migrate → retire loop, triggered early instead of after a support ticket. For the fleet-wide view of numbers already flagged, poll /api/v1/numbers/reputation-alerts; the spam-likelihood score is the per-number drill-down that surfaces the risk before it reaches that alert list.

Reputation

Per-number carrier spam-label reputation — how Hiya / TNS / First Orion / Free Caller Registry / Nomorobo label your own outbound number — plus a registration/dispute remediation plan to clear a false “Spam Likely” / “Scam Likely” tag.

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

Returns monitored: false / status: "unknown" until the probe scheduler covers the number. See CNAM & Caller ID for spam-label remediation.

Fleet-wide reputation alerts (dashboard)

Checking numbers one at a time doesn’t scale once you own more than a handful of DIDs. GET /api/v1/numbers/reputation-alerts rolls up every monitored owned DID (at least one carrier observation recorded) and returns only the ones that still need action — currently flagged, at risk, or missing branded-caller registration, and with no open tracked remediation submission covering it yet. This powers the reputation-alerts banner on the Numbers dashboard.

curl "https://api.orbit.devotel.io/api/v1/numbers/reputation-alerts" \
  -H "X-API-Key: dv_live_sk_..."

{
  "data": {
    "summary": {
      "monitored_count": 42,
      "needs_action_count": 3,
      "scam_likely_count": 1,
      "unregistered_count": 1
    },
    "alerts": [
      {
        "phone_number_id": "num_abc123",
        "phone_number": "+14155550100",
        "status": "flagged",
        "worst_label": "scam_likely",
        "flagged_providers": [{ "provider": "hiya", "provider_name": "Hiya" }],
        "unregistered_providers": [],
        "uncovered_providers": [{ "provider": "hiya", "provider_name": "Hiya" }],
        "last_checked_at": "2026-08-10T12:00:00.000Z"
      }
    ],
    "truncated": false
  }
}

The scan is capped at 500 monitored DIDs per call; truncated: true means only the first 500 were scanned, so the counts are a lower bound. A number drops off this list as soon as an operator lodges a tracked submission for every flagged provider via POST .../reputation/submissions — the alert surface only ever shows what still genuinely needs attention.

Closed-Loop Reputation Remediation

Configure and preview an automated healing plan for degraded numbers — quarantine the number, order a clean replacement, migrate its inbound routing / dialer campaigns / SMS sender pools, re-attest, then retire the original — instead of manually swapping a flagged DID after a support ticket.

Read the policy

GET /api/v1/numbers/reputation-remediation-policy

curl "https://api.orbit.devotel.io/api/v1/numbers/reputation-remediation-policy" \
  -H "X-API-Key: dv_live_sk_..."

Returns the current policy plus the server-side defaults (bounds for cooldown hours and the per-run cap). auto_remediate defaults to false — remediation is opt-in.

Configure the policy

PUT /api/v1/numbers/reputation-remediation-policy

curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/reputation-remediation-policy" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "auto_remediate": false,
    "min_trigger_tier": "critical",
    "cooldown_hours": 24,
    "provision_replacement": true,
    "reattest": true,
    "retire_after_migration": true,
    "max_remediations_per_run": 5
  }'

Field	Type	Description
`auto_remediate`	boolean	Master opt-in for UNATTENDED remediation. Defaults to `false` — a plan is always previewable regardless.
`min_trigger_tier`	`poor` \| `critical`	Minimum degraded health tier that triggers a remediation. Defaults to `critical` (worst numbers only).
`cooldown_hours`	number	Hours before the same DID may be remediated again (thrash guard).
`provision_replacement`	boolean	Order a clean replacement DID from inventory before migrating, instead of substituting an already-warmed number. Defaults to `true`.
`reattest`	boolean	Re-run STIR/SHAKEN attestation on a newly-provisioned replacement. Defaults to `true`.
`retire_after_migration`	boolean	Release / retire the degraded DID once its traffic has moved off it. Defaults to `true`.
`max_remediations_per_run`	number	Per-run cap on how many DIDs a single remediation tick processes.

Requires the numbers:write scope (owner / admin).

Preview the plan

GET /api/v1/numbers/reputation-remediation-plan

curl "https://api.orbit.devotel.io/api/v1/numbers/reputation-remediation-plan" \
  -H "X-API-Key: dv_live_sk_..."

Returns the ordered closed-loop steps (quarantine → provision_replacement → migrate_inbound_routes / migrate_dialer_campaigns / migrate_sender_pools → reattest → retire) the current policy would run for every currently-degraded (poor/critical) owned DID, plus a summary of how many would be remediated, deferred (cooldown), capped, or skipped. This is a preview only — it never mutates routing, orders a replacement, or retires a number, regardless of the auto_remediate flag.

Usage Analytics

Per-number usage rollup over a configurable window.

curl "https://api.orbit.devotel.io/api/v1/numbers/num_abc123/usage-analytics?window=30d" \
  -H "X-API-Key: dv_live_sk_..."

Parameter	Values	Default	Description
`window`	`24h` \| `7d` \| `30d` \| `90d`	`30d`	Rollup window.

Returns call + message counts, durations, and delivery outcomes scoped to the number and window.

Branded-Calling Analytics

Per-number Rich Call Data (RCD) answer-rate uplift: compares the number’s outbound answer rate for the requested window against the immediately-preceding equal-length baseline, alongside your organization’s branded-calling status — so a customer who registered a brand profile can see the contact-center answer-rate lift.

curl "https://api.orbit.devotel.io/api/v1/numbers/num_abc123/branded-calling-analytics" \
  -H "X-API-Key: dv_live_sk_..."

Getting Started

Channels

Channels (Voice)

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Number health, warming, and carrier reputation tracking

Number Health & Reputation

Warming

Health (deliverability)

Health trend & forecast (predictive)

Predictive spam-likelihood scoring & remediation playbook

Reputation

Fleet-wide reputation alerts (dashboard)

Closed-Loop Reputation Remediation

Read the policy

Configure the policy

Preview the plan

Usage Analytics

Branded-Calling Analytics

​Number Health & Reputation

​Warming

​Health (deliverability)

​Health trend & forecast (predictive)

​Predictive spam-likelihood scoring & remediation playbook

​Reputation

​Fleet-wide reputation alerts (dashboard)

​Closed-Loop Reputation Remediation

​Read the policy

​Configure the policy

​Preview the plan

​Usage Analytics

​Branded-Calling Analytics

Number Health & Reputation

Warming

Health (deliverability)

Health trend & forecast (predictive)

Predictive spam-likelihood scoring & remediation playbook

Reputation

Fleet-wide reputation alerts (dashboard)

Closed-Loop Reputation Remediation

Read the policy

Configure the policy

Preview the plan

Usage Analytics

Branded-Calling Analytics