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

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.

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

curl "https://api.orbit.devotel.io/api/v1/numbers/export?format=json&status=active" \
  -H "X-API-Key: dv_live_sk_..."

[
  {
    "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.

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

{
  "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 webhook event so your integration can auto-reprovision without polling.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

Inventory & Export

Inventory & Export

List Numbers

Export Inventory

Query parameters

Response headers

CSV columns

JSON example

Low-Stock Inventory Alerts

Query parameters

Response

​Inventory & Export

​List Numbers

​Export Inventory

​Query parameters

​Response headers

​CSV columns

​JSON example

​Low-Stock Inventory Alerts

​Query parameters

​Response

Inventory & Export

List Numbers

Export Inventory

Query parameters

Response headers

CSV columns

JSON example

Low-Stock Inventory Alerts

Query parameters

Response