Virtual numbers
Admin API for virtual number pool management.
Overview
Virtual numbers are E.164 phone numbers assigned per unit (ADR-001). Each tenant has a cap of unitCount + 5 numbers.
Deep runbook: docs/VIRTUAL_NUMBER_MANAGEMENT.md.
Endpoints
Base path: /api/admin/virtual-numbers
| Method | Path | Description |
|---|---|---|
GET | / | List numbers (filter by status, tenant) |
GET | /summary | Pool summary counts |
GET | /health | Sync health with carrier |
GET | /settings | Auto-provision settings |
PUT | /settings | Update settings |
POST | /search-available | Search carrier inventory |
POST | /purchase | Buy and add to pool |
POST | /sync | Sync with Twilio/Telnyx account |
POST | /reconcile | Reconcile DB vs carrier |
POST | / | Create number record |
GET | /:id | Fetch one |
PUT | /:id | Update |
POST | /:id/assign | Assign to unit |
POST | /:id/release | Release from unit (may quarantine) |
Key fields
| Field | Notes |
|---|---|
e164 | E.164 format (unique) |
telephonyProvider | twilio or telnyx |
unitId | Assigned unit (null when in pool) |
quarantineUntil | Cooling period after release |
status | Pool lifecycle state |
Provider behavior
VirtualNumber.telephonyProvideris canonical for inbound voice routing.- VNMS purchase accepts
providerparam; defaults depend on property override. - When
TELEPHONY_PROVIDER=telnyx, sync uses Telnyx inventory API.
Related
Last verified: 2026-06-21 (commit 293c4a7)