> ## 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.

# Order international freephone numbers end to end

> Take a Universal International Freephone Number (UIFN) or International Toll-Free Service (ITFS) order from coverage check to activation — pick the class and countries, set the emergency address, route inbound calls, prove the calls, and keep the number healthy.

# 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

|                          | UIFN order                                   | ITFS order                                                            |
| ------------------------ | -------------------------------------------- | --------------------------------------------------------------------- |
| Destination per call leg | Global support queue                         | Regional (EU) support queue                                           |
| Countries                | HK, SG, JP on the shared `+800` GSN          | GB, DE, FR with per-country access numbers                            |
| Routing                  | one prefix DNIS rule (`+800`) → global queue | per-country prefix rules (`+44 800`, `+49 800`, `+33 800`) → EU queue |

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.

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/numbers/international-freephone/coverage \
  -H "X-API-Key: dv_live_sk_your_key_here"
```

```json theme={null}
{
  "data": {
    "uifn": {
      "countryCode": "800",
      "countries": ["AT", "AU", "BE", "BR", "CH", "CL", "CN", "CO", "CY", "CZ", "DE", "DK", "EE", "ES", "FI", "FR", "GB", "GR", "HK", "HU", "IE", "IL", "IN", "IT", "JP", "KR", "LU", "MY", "NL", "NO", "NZ", "PH", "PL", "PT", "SE", "SG", "SK", "TH", "TW", "US", "ZA"]
    },
    "itfs": {
      "countries": ["AR", "AT", "AU", "BE", "BR", "CA", "CH", "CL", "CN", "CO", "CZ", "DE", "DK", "EE", "ES", "FI", "FR", "GB", "GR", "HK", "HU", "ID", "IE", "IL", "IN", "IT", "JP", "KR", "LU", "MX", "MY", "NL", "NO", "NZ", "PE", "PH", "PL", "PT", "RO", "SE", "SG", "SK", "TH", "TR", "TW", "US", "VN", "ZA"]
    }
  }
}
```

**Step two — per-country [country capabilities](/numbers/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](/numbers/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.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/international-freephone/search \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "numberClass": "uifn",
    "countryCodes": ["HK", "SG", "JP"],
    "requestedGsn": "12345678"
  }'
```

**Then open the order.** `POST /api/v1/numbers/international-freephone` creates a `draft` order:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/international-freephone \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "numberClass": "uifn",
    "label": "Global support line",
    "businessName": "Acme Global Ltd",
    "requestedGsn": "12345678",
    "routeToE164": "+14155550100",
    "countryCodes": ["HK", "SG", "JP"]
  }'
```

Field rules the API enforces (a 422 repeats them):

| Field          | Rule                                                                                                                                                                                |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `numberClass`  | `uifn` or `itfs`.                                                                                                                                                                   |
| `label`        | 1–120 characters; the name the dashboard shows for the order.                                                                                                                       |
| `businessName` | 1–200 characters; the applicant name filed with the registry / provider.                                                                                                            |
| `requestedGsn` | Exactly 8 digits, UIFN only. Passing one on an ITFS order is a 422.                                                                                                                 |
| `routeToE164`  | E.164 destination metadata (`+[1-9]` plus 7–15 digits) — the number calls terminate toward. Set it at create or later via PATCH; it is routing *metadata*, not a wired termination. |
| `countryCodes` | Up to 200 ISO-3166 alpha-2 codes on create.                                                                                                                                         |

**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).

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/international-freephone/free_9xK2mQp1/countries \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "countryCode": "TH", "status": "requested" }'
```

**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:

| `status`       | Meaning                                                                                            |
| -------------- | -------------------------------------------------------------------------------------------------- |
| `draft`        | Order created; countries and routing being assembled.                                              |
| `submitted`    | Filed with the registry / provider; allocation queued.                                             |
| `provisioning` | Allocation in progress; country legs activate independently.                                       |
| `active`       | Allocated and reachable for inbound calls.                                                         |
| `suspended`    | Billing / compliance hold; resumable, not relinquished.                                            |
| `cancelled`    | Relinquished (terminal). `DELETE /numbers/international-freephone/{id}` with an optional `reason`. |

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](/guides/buy-numbers) 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](/numbers/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.

<Note>
  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.
</Note>

***

## 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](/guides/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](/numbers/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](/guides/telq-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](/numbers/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."

<Warning>
  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."
</Warning>

***

## Troubleshooting

| Symptom                                                        | Cause                                                           | Fix                                                                                                                     |
| -------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| 422 "requestedGsn applies to UIFN orders only"                 | Vanity GSN passed on an ITFS order                              | Drop `requestedGsn`; ITFS access numbers are assigned                                                                   |
| 422 "GSN must be exactly 8 digits"                             | Malformed UIFN vanity request                                   | Pass exactly 8 numeric digits, or omit for auto-assignment                                                              |
| 409 "Freephone order cannot move from 'active' to 'submitted'" | Illegal lifecycle hop (e.g. re-submitting a live order)         | PATCH the draft fields instead; lifecycle transitions are one-directional                                               |
| Country leg stays `requested` after others activate            | Per-country carrier lag — activation is independent per country | Test that leg with live-number testing; re-check the health view before escalating                                      |
| Calls ring out from one country only                           | Routing or settlement issue on that leg                         | Check the leg's health snapshot; verify the DNIS prefix rule actually matches that access number                        |
| Coverage says a country is closed                              | UIFN participation / ITFS footprint is catalog-gated            | Use the other class (ITFS vs UIFN), or route via an ordinary local DID from the [buy-numbers](/guides/buy-numbers) flow |
| Existing toll-free estate from another carrier                 | Freephone ordering covers new inventory only                    | Migrate via the [porting](/numbers/porting) flow                                                                        |

***

## Related

* [Country capabilities](/numbers/country-capabilities) — pre-check per-country inventory before shortlisting.
* [Regulatory preview](/numbers/regulatory-preview) — per-country requirements, inline before you order.
* [Emergency address (E911)](/numbers/emergency-address) — the dispatchable-address registration your destination needs.
* [DNIS pattern routing](/guides/dnis-pattern-routing) — one rule answers the whole freephone block.
* [Live-number testing](/guides/telq-live-number-testing) — prove the inbound path with a real call or SMS.
* [Number health](/numbers/health) — warming, deliverability, and settlement signals per number.
* [Number porting](/numbers/porting) — bring existing international toll-free numbers onto Orbit.
* [Buy and provision numbers](/guides/buy-numbers) — the standard flow for ordinary local / mobile / toll-free DIDs.