​

Inbound health: find and repair numbers that silently drop inbound SMS

​

How gap detection works

• Only SMS-capable numbers you own are checked. Voice-only numbers never appear, because inbound routing for texts is irrelevant to them.
• Shared pool numbers are excluded. A number that also appears in the platform inventory resolves inbound before the reverse map is even consulted, so flagging it would misreport a healthy route as a gap.

​

Walk the Inbound health tab

• Healthy zero-state. When gapCount is zero, the tab tells you every SMS-capable number resolves correctly — no action is needed and the tab can stay closed another cycle.
• Error state. If the health read itself failed, the tab shows an error instead of a stale table. Refresh; a persisted read failure is worth an escalation note rather than a repair attempt.
• Gap table. Each row shows one affected number, masked (first three digits plus the last two, e.g. +15********71) so the raw digits never leave the API, together with its current status (active, pending_compliance, or suspended — the statuses that count as owned). The table lists at most 250 rows; the gapCount total above it always reports the full count, so a saturated table is annotated rather than silently truncated.

​

Repair from the tab

• Role gate. Reading the tab is allowed for every role that can see Numbers. Triggering the repair requires owner, admin, or developer in the dashboard, or an API key with numbers write for API calls — a viewer sees the same honest gap list but cannot mutate it.
• Idempotent. The repair inserts only rows still missing at insert time and ignores rows that already exist. Re-running it after the gap closes is a no-op, and a concurrent purchase completing at the same moment cannot create a duplicate entry.
• Expected result. After a successful repair, the affected numbers resolve inbound immediately — send a test text to confirm, or re-read the health endpoint and expect gapCount: 0.

​

API equivalents

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

{
  "data": {
    "gaps": [
      { "phoneNumberMasked": "+15********71", "status": "active" }
    ],
    "gapCount": 1,
    "resolverOrgScanCap": 250
  }
}

curl -X POST "https://api.orbit.devotel.io/api/v1/numbers/inbound-resolution/repair" \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "data": {
    "orgId": "org_01J9Z8ABCDEF",
    "tenantId": "a1b2c3d4-...",
    "rowsInserted": 1
  }
}

const health = await fetch(
  'https://api.orbit.devotel.io/api/v1/numbers/inbound-resolution/health',
  { headers: { 'X-API-Key': process.env.ORBIT_API_KEY! } },
).then((r) => r.json())

if (health.data.gapCount > 0) {
  const repair = await fetch(
    'https://api.orbit.devotel.io/api/v1/numbers/inbound-resolution/repair',
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.ORBIT_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: '{}',
    },
  ).then((r) => r.json())
  console.log(`re-registered ${repair.data.rowsInserted} numbers`)
}

​

When repair alone does not fix inbound delivery

• The hourly background sweep runs the same repair the button triggers, so a gap the repair reports as fixed will not re-open — and re-running it is never harmful.
• Each number also carries an optional per-number SMS route override. If that override is set to disabled, the inbound text resolves and stores but dispatches nowhere — the repair cannot change that.
• Inbox assignment and webhook delivery are separate steps downstream of resolution.

​

See also

• Troubleshooting: inbound SMS to your number never arrives — the ordered runbook this page hands off to when repair is not enough.
• Inbound message resolution — how a number resolves to your workspace, and the four per-number SMS route types.
• Inbound number routing — set the per-number route override the health tab cannot fix.
• Bulk number-order history — reconcile provisioning after a bulk buy.