> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Inventory & Export > List your purchased numbers, export the full inventory as CSV or JSON, and watch low-stock alerts # Inventory & Export Every number you own lives in your tenant inventory. List it page-by-page, export the whole set for finance reconciliation, and monitor low-stock buckets so you never run dry mid-campaign. All routes are tenant-scoped — you only ever see your own organization's numbers. ## List Numbers ```bash theme={null} curl "https://api.orbit.devotel.io/api/v1/numbers" \ -H "X-API-Key: dv_live_sk_..." ``` The list endpoint is cursor-paginated (25 rows per page by default). For anything over \~100 numbers, use the bulk export below instead of paging. ## Export Inventory Download your entire number inventory in a single request — ideal for reconciling the monthly DID line on your invoice against the active set, or syncing your CMDB. ```bash theme={null} curl "https://api.orbit.devotel.io/api/v1/numbers/export?format=csv" \ -H "X-API-Key: dv_live_sk_..." \ -o phone-numbers-export.csv ``` ### Query parameters | Parameter | Type | Default | Description | | -------------- | ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `format` | `csv` \| `json` | `csv` | Output format. | | `status` | string | `all` | Filter by status. Defaults to `all` so released/parked rows (still billable until parked) are included; pass `active` to narrow. | | `country_code` | ISO 3166-1 alpha-2 | — | Restrict to one country (e.g. `US`). | | `search` | string | — | Free-text match on the number / label. | | `tz` | IANA timezone | — | CSV only. Renders the `created_at` / `assigned_at` / `next_billing_at` columns in this timezone (e.g. `America/New_York`) as `YYYY-MM-DD HH:MM:SS GMT±HH`, matching the dashboard wall clock. Omit to keep UTC ISO-8601. The dashboard export button sends the operator's browser timezone automatically. | | `locale` | BCP-47 locale | `en-US` | CSV only. Locale used when formatting localized timestamps. | ### Response headers | Header | Description | | --------------------- | -------------------------------------------------------------------------- | | `Content-Disposition` | `attachment; filename="phone-numbers-export-YYYY-MM-DD.csv"` (or `.json`). | | `X-Row-Count` | Number of rows in the export. | | `X-Truncated` | `true` when the export hit the 50,000-row cap. | | `X-Truncated-At` | The cap value (`50000`) when truncated. | ### CSV columns Columns are emitted in this exact order (load-bearing for downstream billing tooling — new columns are only ever appended): ``` msisdn, country_code, area_code, status, number_type, capabilities, label, tags, forwarding_number, assigned_to, compliance_profile_id, tfv_status, monthly_cost, created_at, assigned_at, next_billing_at, spend_30d ``` `tfv_status` is the Toll-Free Verification status of the number. It only applies to toll-free DIDs (`not_submitted`, `pending`, `approved`, `rejected`); for every other number type the column reads `N/A` because toll-free verification does not apply. `spend_30d` is the trailing-30-day total spend for the number — recurring monthly charge plus realised usage (voice + SMS + MMS) over the last 30 days — matching the **Spend (30d)** column on the dashboard Numbers list. A number with no traffic shows just its recurring cost; the cell is left blank only if the spend figure could not be computed. ### JSON example ```bash theme={null} curl "https://api.orbit.devotel.io/api/v1/numbers/export?format=json&status=active" \ -H "X-API-Key: dv_live_sk_..." ``` ```json theme={null} [ { "msisdn": "+14155550100", "country_code": "US", "area_code": "415", "status": "active", "number_type": "local", "capabilities": ["sms", "voice"], "label": "Main Support Line", "monthly_cost": "1.50", "created_at": "2026-01-04T12:00:00.000Z", "next_billing_at": "2026-07-04T12:00:00.000Z", "spend_30d": 4.25 } ] ``` Export is a pure read of your local inventory table — no carrier call is made, and it never touches an outbound voice/SMS path. Any dashboard user with read access can export their own organization's inventory. ## Low-Stock Inventory Alerts When you provision numbers from a pool (rotation, sticky-sender, campaign overflow), Orbit tracks how many active DIDs remain per `(country, area-code prefix)` bucket and flags any bucket below your threshold. ```bash theme={null} curl "https://api.orbit.devotel.io/api/v1/numbers/inventory-alerts" \ -H "X-API-Key: dv_live_sk_..." ``` ### Query parameters | Parameter | Type | Default | Description | | --------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `limit` | integer (1–100) | `8` | How many low-stock buckets to return, worst-first. Raise it to page deeper into the alert set (hard ceiling **100**). Values outside the range — or any unparseable value — fall back to the default of `8`. | ### Response ```json theme={null} { "data": { "alerts": [ { "country_code": "US", "area_code_prefix": "415", "available_count": 2, "threshold": 3 } ], "total_alerts": 1, "limit": 8, "threshold": 3, "default_threshold": 3 } } ``` | Field | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `alerts` | The low-stock buckets, sorted worst-first (lowest `available_count` first). This list is capped at `limit`, so by default it returns only the **8** most critical buckets — it is not necessarily the complete set. | | `total_alerts` | The total number of buckets below the threshold, before the `limit` cap is applied. When `total_alerts` is larger than the length of `alerts`, raise `?limit=` (up to 100) to retrieve the rest. | | `limit` | The cap applied to `alerts` on this request — the `?limit=` value you sent, or **8** when omitted. | | `threshold` | The effective low-stock threshold used for this tenant. | | `default_threshold` | The platform default threshold (**3**). | The threshold defaults to **3** and can be overridden per-tenant via `organizations.settings.numbers.tn_low_stock_threshold`. A daily scheduler emits the low-stock bucket payload through the [`number.inventory.low`](/webhooks/events) webhook event so your integration can auto-reprovision without polling.