Skip to main content

​
Country Capabilities

Before you run a number search, check what’s actually in stock for a country. The country-capabilities endpoint returns a per-(line type × capability) inventory summary so the buy-numbers picker can show you, for example, that the UK has plenty of local-voice numbers but zero SMS-capable mobiles — before you waste a search.

​
Query parameters

​
Response

​
Why this endpoint exists

The Numbers → Buy a number picker in the dashboard renders an “inventory at a glance” row: for each country it calls this endpoint once and uses the counts to pre-dim empty capability buckets, so a shopper who needs two-way SMS in Germany doesn’t run five searches before learning that German locals are voice-only. Calling it yourself gives you the same reality check the console gets — pick countries with stock first, then let the live search enumerate individual numbers inside the buckets that matter to you.

​
How counts aggregate

The summary is the line-type × capability cartesian product of the country’s inventory:
  1. Three line types — mobile, local, toll_free — are probed separately, each against every upstream carrier the country can be served from. All probes run in parallel as a single page per (carrier × line type); one aggregate call fans out roughly six carrier requests and completes in about one carrier round-trip.
  2. Buckets sum across carriers. Provider names are never attributed to a count — local_voice: 100 is the union of however many carriers serve that country.
  3. Counts clamp at 100. Each probe reads one carrier page (carriers cap a page near 100) and each bucket is clamped at 100, so 100 reads as “plenty in stock”. Use the live search to enumerate inside the bucket.
  4. two_way_sms is derived differently. It is not the sum of the SMS buckets. It counts only numbers whose carrier confirms both legs (send and receive) as wired — which excludes send-only toll-free numbers entirely. Treat it as the authoritative “can this country do two-way SMS” signal rather than inferring two-way from the raw SMS buckets.
  5. The result is cached. A clean aggregation is held server-side for 5 minutes; every response carries last_updated so you know which window you’re reading.
Counts reflect carrier-side stock only. Numbers already held by the platform for resale into your organization are intentionally not double-counted here.

​
Field-by-field walkthrough

​
Scenario: toll_free_sms says 40 but two_way_sms says 0

Toll-free SMS (post-verification, US/CA class routes) can send but the inbound leg is not wired on toll-free — so a country can report toll_free_sms: 40 alongside two_way_sms: 0. If you need recipients to reply, do not steer toward toll-free just because the toll_free_sms bucket is non-zero; check two_way_sms first and pick a local or mobile bucket when it must be two-way.

​
Scenario: local_sms is 0 in the UK, Germany, France

A zero local_sms bucket in most European countries is structural: landlines there don’t carry SMS at the carrier level, at any price. The UK picker showing “Local (SMS) — 0” isn’t out of stock; it’s telling you to buy a mobile number for SMS or accept a voice-only local. This is the pre-dim case the picker exists to prevent you discovering after purchase.

​
Scenario: US response shaping with 10DLC

For country=US, upstream carriers hold no mobile DID inventory at all — every US A2P sender is a 10DLC-registered local number. So us_uses_10dlc: true and the response carries the extra local_sms_via_10dlc count: the number of US locals eligible to register a 10DLC campaign. Read that field instead of treating mobile_sms: 0 as a dead end.

​
Caching contract

Server-side and client-side caches deliberately agree, so plan around the window rather than fight it:
  • Server TTL: 5 minutes per country. The cache key is per-country and shared across tenants (carrier inventory is identical for everyone), so your request after 5 minutes re-probes the carriers; requests inside the window are served instantly.
  • Degraded results self-heal in ~20 seconds. If any carrier probe failed during aggregation, the summary may contain a false zero (a swallowed carrier error, not real “no stock”). Orbit caches a degraded summary for only ~20 seconds instead of the full 5 minutes, so a flap corrects itself on the next request instead of poisoning the picker for minutes.
  • Dashboard refetch cadence: 5 minutes. The console’s stale-time matches the server TTL by design; your own client should do the same. Refetching more often than the TTL just re-reads the cache.
  • How stale counts show. A number bought or released inside the window won’t move the count until the window rolls over. last_updated tells you the aggregation moment; when a count must be exact, follow up with the live number search, which always re-reads the carriers.

​
Limitations

  • Counts are bucketed and clamped at 100. 100 means “plenty in stock”, not exactly one hundred — refine with the live search after picking a country.
  • Provider names are never surfaced. Each bucket is the cross-carrier union; routing across carriers is an internal concern.
  • Country-level summary, not per-number availability. A non-zero bucket guarantees stock exists; which specific numbers, their price, and their regulatory requirements come from the live search and regulatory preview.
  • Carrier-side stock only. Platform-held resale inventory is not counted.
Rate limit matches other read-side numbers routes (60 requests/minute). With the 5-minute server cache, even polling every few seconds costs you nothing extra against the carriers — but your own integration should cache too.

​
See also