Skip to main content

​
International Freephone (UIFN / ITFS) end to end

One inbound line that works across borders comes in two shapes:
  • UIFN — a Universal International Freephone Number under the ITU-T E.169 registry. One number, +800 followed by an 8-digit Global Subscriber Number (GSN), activated per participating country. A caller in Tokyo and a caller in Paris dial the same +800 digits.
  • ITFS — International Toll-Free Service. A set of per-country in-country toll-free numbers (a UK +44 800…, a German +49 800…, and so on), all terminating to your one destination. Callers dial a familiar national format.
Freephone numbers are inbound-only. An order here provisions inbound reachability and inbound routing; it never opens an outbound voice or SMS path — outbound termination keeps exiting only through Orbit’s own network. This guide walks the full loop. A worked example runs through the whole thing: one UIFN order plus one ITFS order, each routed to its own queue.
  1. Check scope and eligibility per country.
  2. Search availability, then open the order.
  3. Set the emergency address before activation.
  4. Route inbound calls with DNIS rules.
  5. Line up the compliance posture.
  6. Test with a live number and watch number health.

​
Worked example at a glance

The sections below expand each row.

​
1. Scope and eligibility per country

Before you pick a class, check two catalogues: whether the class even reaches your target countries, and what those countries charge per line. Step one — the freephone coverage catalog. GET /api/v1/numbers/international-freephone/coverage returns the static participating-country list per class. UIFN participation is governed by the ITU-T E.169 registry — each administration opts its country’s carriers into +800 reachability — so a country absent from the list simply cannot carry a UIFN, regardless of demand. ITFS availability tracks the provider footprint and covers a different (overlapping but not identical) set.
Step two — per-country country capabilities. The coverage catalog says the class reaches a country; the country-capabilities endpoint says what inventory that country actually carries today (line types, capability buckets, a “plenty in stock” signal). Run it for every country on your shortlist before you design the campaign page or print the number anywhere. Eligibility rules worth noting before you pick the class:
  • One UIFN is one global number. Countries you add later activate on the same GSN — there is no per-country UIFN. If two regions need different numbers (different call treatment, different languages on a greeting), that is two ITFS orders, not one UIFN.
  • Per-country activation is independent under both classes. A country leg can sit requested while others are active; call traffic works country by country as legs activate.
  • Eligibility is per tenant, not global. The catalog is the same for every organization; what you may order depends on the regulatory requirements each country attaches (section 5), which are checked per order at your organization level.
  • Bringing numbers you already hold — an existing international toll-free estate moves through the porting flow, not through a new freephone order: pay attention in particular to country-by-country FOC dates, because a partial port leaves two live paths to the same queue.

​
2. Search availability, then open the order

Search first. POST /api/v1/numbers/international-freephone/search checks eligibility against the catalog and your organization’s existing inventory without creating anything. For UIFN, pass an optional 8-digit vanity requestedGsn; for ITFS the per-country access numbers are assigned, so a search carries only the class and the country list.
Then open the order. POST /api/v1/numbers/international-freephone creates a draft order:
Field rules the API enforces (a 422 repeats them): Add or adjust country legs while the order is a draft. POST /api/v1/numbers/international-freephone/{id}/countries upserts one leg: for ITFS the leg carries its in-country toll-free accessNumber once assigned; for UIFN the leg carries only the country’s activation state on the shared +800 GSN (no per-leg number).
Submit when the draft is complete. POST /api/v1/numbers/international-freephone/{id}/submit files the order with the ITU-T TSB registry (UIFN) or the freephone provider (ITFS). The status flips to submitted, the GSN or access numbers are reserved, and allocation queues. From here the lifecycle is operator-relayed — allocation runs through the registry and per-country carriers, not through a self-serve call — and the order moves submitted → provisioning → active as the upstream steps land: Track the transition with GET /api/v1/numbers/international-freephone/{id} and adjust the label or routeToE164 later with PATCH on the same path. In the dashboard, the same surface lives at Numbers → International freephone; the standard buy-numbers flow remains the path for ordinary local / mobile / domestic toll-free DIDs.

​
3. Set the emergency address before activation

Freephone is inbound, so callers do not dial emergencies inward to you — but the destination your freephone terminates toward (routeToE164) is a number people may dial outbound from, and that number needs its dispatchable emergency address registered before the freephone goes live. Do not wait for activation day to discover the destination’s address paperwork is missing. Register the E911 document per emergency address: each destination number carries one registered dispatchable address, validated at write time. Treat this as a hard gate in your runbook — the freephone order says where calls land, so the address of the landing point must be settled first.
Orbit’s outbound 911 posture is block-and-disclaim: a registered address records the dispatchable location but does not by itself enable outbound emergency dialing from the destination number.

​
4. Route inbound calls with DNIS rules

Activation makes the number reachable; a routing rule decides where the call goes. For freephone stock the right tool is DNIS pattern routing — one rule matches the whole block and holds even as more legs activate, instead of one routing entry per country. In the worked example:
  • The UIFN order funnels every participating country to the global queue with one prefix rule on +800 — every leg (HK, SG, JP, and any leg added later) matches it.
  • The ITFS order funnels each country to the EU queue with one prefix rule per access-number prefix (+44 800…, +49 800…, +33 800…). Per-number entries still win over patterns, so a later exception is an override, not a rewrite.
Set the routeToE164 metadata on the order anyway — it is the declared destination, and a DNIS pattern that points elsewhere is a drift the pattern’s precedence rules will silently apply. Keep the two consistent.

​
5. Line up the compliance posture

Every country attaches its own identity, address, and documentation requirements to number ownership, and those gates sit between submitted and active. Run the regulatory preview per target country before you open the order — it lists the documents and identity fields the country’s onboarding will require, so the registry submission does not stall on a missing address or an unverified business document. This is a tenant-owned control: the preview tells your organization what to file, and the documents you attach are scoped to your own tenant. There is no global allow/deny list — a country open in the coverage catalog is open, and the per-country requirements simply gate your activation until cleared. Scope note: the compliance bar here is about owning the number. How you use an inbound line (recording, retention, consent) is covered on the compliance pages; nothing in freephone provisioning relaxes or imposes those controls.

​
6. Test with a live number, then watch health

Prove the calls before you announce the number. Run a round of live-number testing against each active leg: place a real call or SMS from a test handset on the destination network and confirm the inbound path answers where your DNIS rules say it should. A freephone launch fails most often right here — the registry says active, but the call never lands because a per-country carrier lagged or the routing rule points at a queue with no agents. Testing with live reachability catches that before your customers do. Then keep it healthy. The number health pages track per-number warming, deliverability, reputation, and (for voice numbers) the settlement/reachability signals the dashboard aggregates. After activation, watch the health view per leg: a country that flips active but shows settlement lag or a degraded health score is the same thing a carrier would later report as “calls from that country ring out” — visible to you days earlier. For ITFS estates with many legs, health-per-leg is the difference between “the line is down” and “Germany is down.”
Health snapshots are locally-persisted reads — no live carrier call, no outbound path. They degrade gracefully: a missing snapshot means “no signal yet,” not “number broken.”

​
Troubleshooting