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_..."

import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.request("GET", "/numbers", undefined);

from orbit_sdk import OrbitClient
client = OrbitClient.from_env()

res = client.request("GET", "/numbers")

package main
import (
	"context"
	"os"
	"github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil { panic(err) }

	var out0 map[string]any
	err = client.Request(context.Background(), "GET", "/numbers", nil, nil, &out0, "")
	if err != nil { panic(err) }
}

require "orbit_sdk"
client = OrbitSdk::Client.from_env

res = client.request("GET", "/numbers")

<?php
require __DIR__.'/vendor/autoload.php';
use Devotel\Orbit\OrbitClient;
$client = OrbitClient::fromEnv();

$res = $client->request("GET", "/numbers");

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

import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.request("GET", "/numbers/export?format=csv", undefined);

from orbit_sdk import OrbitClient
client = OrbitClient.from_env()

res = client.request("GET", "/numbers/export?format=csv")

package main
import (
	"context"
	"os"
	"github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil { panic(err) }

	var out0 map[string]any
	err = client.Request(context.Background(), "GET", "/numbers/export?format=csv", nil, nil, &out0, "")
	if err != nil { panic(err) }
}

require "orbit_sdk"
client = OrbitSdk::Client.from_env

res = client.request("GET", "/numbers/export?format=csv")

<?php
require __DIR__.'/vendor/autoload.php';
use Devotel\Orbit\OrbitClient;
$client = OrbitClient::fromEnv();

$res = $client->request("GET", "/numbers/export?format=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	—	Accepted for backward compatibility. The file’s date columns are always written in UTC ISO-8601 with a trailing `Z` (see below), so this parameter no longer changes the file’s date values. The on-page Numbers table still renders in your timezone; only the file is UTC.
`locale`	BCP-47 locale	`en-US`	Accepted for backward compatibility. The file’s date columns are always UTC ISO-8601 regardless of locale.

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. created_at, assigned_at, and next_billing_at are written in UTC ISO-8601 with a trailing Z and second precision — for example 2026-09-01T08:46:36Z. This is the format every spreadsheet (Excel, Google Sheets, Numbers) and every standard date parser reads as the same UTC instant, regardless of your time zone. An empty date (the number was never assigned, has no next billing date, etc.) is an empty cell. The on-screen Numbers table still renders these dates in your timezone; only the file uses the UTC form, so two operators in different zones always get byte-identical files for the same inventory.

JSON example

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

import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.request("GET", "/numbers/export?format=json&status=active", undefined);

from orbit_sdk import OrbitClient
client = OrbitClient.from_env()

res = client.request("GET", "/numbers/export?format=json&status=active")

package main
import (
	"context"
	"os"
	"github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil { panic(err) }

	var out0 map[string]any
	err = client.Request(context.Background(), "GET", "/numbers/export?format=json&status=active", nil, nil, &out0, "")
	if err != nil { panic(err) }
}

require "orbit_sdk"
client = OrbitSdk::Client.from_env

res = client.request("GET", "/numbers/export?format=json&status=active")

<?php
require __DIR__.'/vendor/autoload.php';
use Devotel\Orbit\OrbitClient;
$client = OrbitClient::fromEnv();

$res = $client->request("GET", "/numbers/export?format=json&status=active");

[
  {
    "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:00Z",
    "next_billing_at": "2026-07-04T12:00:00Z",
    "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.

Export from the dashboard

The same export is one click away in the dashboard — no API key needed.

Open Numbers in the dashboard.
Click Export inventory (CSV) in the page header (next to Buy Number). A spinner shows while the file generates, then the browser downloads phone-numbers-export-YYYY-MM-DD.csv and a toast confirms the download.

What the button sends for you:

Dates are always UTC in the file. The created_at / assigned_at / next_billing_at columns are written in UTC ISO-8601 with a trailing Z (e.g. 2026-09-01T08:46:36Z), so the file is identical for every operator regardless of their time zone and every spreadsheet or date parser reads the value as the same instant. The on-screen Numbers table still renders in your timezone; only the file uses UTC. The button still sends your browser’s timezone and locale for backward compatibility, but they no longer change the file’s date values.
Full inventory, not the visible slice. The export always covers the whole inventory — it does not inherit status-tab, country, or search filters you set on the list. To narrow a dashboard export, export everything and filter the CSV, or call the API with ?status=…&country_code=…&search=….
50,000-row cap. Exports stop at 50,000 rows. When the cap hits, the API sets X-Truncated: true and X-Truncated-At: 50000 on the response — the CSV you receive is sorted and complete up to the cap. Narrow with the query parameters above to get under it.

The button always downloads the CSV format. If you need the JSON projection or a pre-filtered set, call GET /numbers/export directly with the parameters above.

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_..."

import { Devotel } from '@devotel-orbit/node';
const orbit = new Devotel({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.request("GET", "/numbers/inventory-alerts", undefined);

from orbit_sdk import OrbitClient
client = OrbitClient.from_env()

res = client.request("GET", "/numbers/inventory-alerts")

package main
import (
	"context"
	"os"
	"github.com/devotel/orbit-go/orbit"
)

func main() {
	client, err := orbit.NewClient(os.Getenv("ORBIT_API_KEY"))
	if err != nil { panic(err) }

	var out0 map[string]any
	err = client.Request(context.Background(), "GET", "/numbers/inventory-alerts", nil, nil, &out0, "")
	if err != nil { panic(err) }
}

require "orbit_sdk"
client = OrbitSdk::Client.from_env

res = client.request("GET", "/numbers/inventory-alerts")

<?php
require __DIR__.'/vendor/autoload.php';
use Devotel\Orbit\OrbitClient;
$client = OrbitClient::fromEnv();

$res = $client->request("GET", "/numbers/inventory-alerts");

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.

The API response carries no severity field. Severity levels exist only in the dashboard banner (below), which derives them from available_count relative to threshold. If you build your own alert surface, replicate that derivation — the rule is documented in the banner section.

The dashboard consumes this endpoint for you and shows the result as a banner at the top of the Numbers page — the same data, no polling script required.

Hidden at steady state. When no bucket is below the threshold (total_alerts: 0) the banner renders nothing — absence means healthy stock, not an error. It also stays hidden while the alerts query is in flight, so it never flashes on page load.
One row per bucket. Each row names a (country, area_code_prefix) bucket and shows its current available_count against your configured threshold — for example US · 415 — 2 available (threshold 3). When more buckets are low than the banner displays you get a + N more buckets line, mirroring total_alerts - alerts.length from the API.
Two severity tiers. The whole banner takes the colour of its worst row:
- Critical (red) — the bucket’s available_count is at or below half the threshold (available_count <= threshold / 2). At the default threshold of 3, a bucket with 0 or 1 available numbers is critical.
- Warning (amber) — the bucket is below the threshold but above the half-threshold line.
Severity level is also carried by an icon and an accessible label, never by colour alone. The dashboard computes severity client-side from available_count and threshold; the API intentionally ships the raw counts only, so your own integration can apply the same rule (or your own).
Buy more from the banner. The banner’s Buy numbers action takes you straight to the buy flow for replenishment. The purchase draws from your existing wallet balance — you are only asked to top up when the balance cannot cover the order.

Reads degrade, never 503

GET /numbers/inventory-alerts is an idempotent read with a deliberate failure policy: when the inventory store is briefly unavailable — a tenant mid-provisioning, a transient database blip, or a statement timeout — the endpoint returns the same empty envelope it returns when every bucket is healthy (alerts: [], total_alerts: 0) instead of a 503. The banner hides on that response and comes back on the next successful poll, so a blip reads as “no low-stock alerts” for a moment rather than as an error page. Design your own consumer the same way: treat an empty alerts array as “nothing actionable right now”, never as proof of healthy stock after a failed request.

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Tutorials

Changelog

Number inventory export and low-stock alerts

Inventory & Export

List Numbers

Export Inventory

Query parameters

Response headers

CSV columns

JSON example

Export from the dashboard

Low-Stock Inventory Alerts

Query parameters

Response

Low-inventory banner (dashboard)

Reads degrade, never 503

​Inventory & Export

​List Numbers

​Export Inventory

​Query parameters

​Response headers

​CSV columns

​JSON example

​Export from the dashboard

​Low-Stock Inventory Alerts

​Query parameters

​Response

​Low-inventory banner (dashboard)

​Reads degrade, never 503

Inventory & Export

List Numbers

Export Inventory

Query parameters

Response headers

CSV columns

JSON example

Export from the dashboard

Low-Stock Inventory Alerts

Query parameters

Response

Low-inventory banner (dashboard)

Reads degrade, never 503