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

# Read the outbound voice country-coverage matrix

> Open the standalone Voice → Country coverage page, read the enabled / restricted / disabled verdict per destination, then gate an agent's outbound list with the tenant-owned country allowlist.

# Read the outbound voice country-coverage matrix

**Voice → Country coverage** is the dashboard's standalone read of the
outbound destination matrix. Run it while you set up an agent or a
workspace's outbound reach: every destination ranks **enabled**,
**restricted**, or **disabled**, and a flagged destination surfaces on the
screen before your first call — not as a softswitch rejection on a live
dial list.

**Base path:** `GET /api/v1/voice/coverage`

**Base surface:** dashboard — **Voice → Country coverage**.

The verdicts are advisory reference data. They never pick a carrier —
every outbound call routes over the same Devotel wholesale softswitch —
and they never impose a platform-wide block: how your workspace treats a
flagged destination is the **tenant-owned policy** you set yourself. The
enforcement half of that pattern is the workspace's
[outbound country allowlist](/compliance/posture-overview), a separate
tenant-scoped setting you pair with this matrix; the matrix tells you
which destinations need a policy, the allowlist is the policy.

***

## 1. What the matrix ranks

Each row anchors one destination country to four attributes:

* **Availability** — whether outbound voice terminates there at all
  (enabled, restricted, or disabled).
* **Regulation tier** — for a restricted row, which regulator attaches a
  condition (sender-ID registration, a local-presence rule, a
  promotional-call filing).
* **Number constraints** — whether the destination demands a registered
  calling party or local presence before AI voice reaches it.
* **Termination reach** — for a disabled row, whether sanctions or the
  absence of a terminating carrier close the destination.

One of three statuses per country:

* **Enabled** — outbound calls proceed with no attached regulatory
  condition.
* **Restricted** — the destination is reachable, but its regulator
  attaches a condition; the reason column names it.
* **Disabled** — the destination is not usable for outbound voice —
  sanctions, or no terminating carrier.

## 2. Reading the dashboard surface

Open **Voice → Country coverage**. Five parts of the page:

* **Status totals.** Three cards count destinations per status — a quick
  read on how much of the matrix is flagged.
* **Check a destination.** Paste an E.164 number (`+905551234567`) and the
  page runs the same pre-call coverage check the dispatch path runs, so
  the verdict you see is what the dial path logs:
  * A country in the matrix resolves to its verdict and reason.
  * A country not in the matrix answers *No coverage entry resolved* —
    dispatch treats unknown countries as a soft warn and lets the
    softswitch arbitrate.
  * A malformed number resolves to an unparsed-destination note rather
    than a verdict.
* **The matrix table.** One row per country: ISO code, country name,
  dialing prefix, status badge, and the reason column for flagged rows.
* **Version stamp.** The page header shows the matrix version, so a
  re-check after coverage data moves is visible.
* **Failure honesty.** If the coverage endpoint cannot be read, the page
  shows an explicit error card with a retry and hides the totals instead
  of rendering `0 / 0 / 0` as if your workspace had no coverage.

## 3. Consuming the coverage API

The same data is readable over the public API:

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

| Field        | Type   | Meaning                                                                                             |
| ------------ | ------ | --------------------------------------------------------------------------------------------------- |
| `iso2`       | string | ISO 3166-1 alpha-2 destination code — match this against your contact data, not the free-text name. |
| `name`       | string | Display name, as the dashboard matrix renders it.                                                   |
| `e164Prefix` | string | Numeric E.164 prefix without the `+` — useful when contacts store numbers without country metadata. |
| `status`     | string | `enabled`, `restricted`, or `disabled`.                                                             |
| `reason`     | string | Regulator or termination citation on a flagged row; empty for `enabled`.                            |

The response returns the whole matrix in one shot — no pagination — sorted
by ISO code, with a `version` stamp to key a cache to. It changes rarely,
so cache it in minutes rather than per dial render. Append `?to=<e164>` to
run the destination probe described above.

## 4. Gating agent outbound to allowed countries

The matrix is advisory; the actual gate is your workspace's
**outbound country allowlist** — the tenant-scoped Compliance control.

1. **Read the matrix** and decide, per flagged destination, what your
   workspace accepts.
2. **Set the allowlist** to the ISO codes you accept:

```bash theme={null}
curl -X PUT "https://orbit.devotel.io/api/v1/settings/compliance/country-allowlist" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"countries": ["US", "CA", "GB", "DE", "FR", "ES", "MX", "ZA"]}'
```

3. The allowlist **fails closed once set** — an off-list destination is
   rejected on every send — and it applies to voice and messaging alike.
   An unset allowlist is fail-open.

Scrub an agent's destination list against the matrix once, before the
first batch, and record the approval as part of your workspace's
compliance configuration. The same verdict you see on the dashboard page
is what the dispatch path logs as a non-blocking structured advisory event
for your audit trail.

## 5. Worked example — US/EU/LATAM restrictors

A workspace runs outbound to North America, Europe, Mexico, and South
Africa. In the shipped matrix those rows read:

| ISO | Country        | Prefix | Verdict | Reason |
| --- | -------------- | ------ | ------- | ------ |
| US  | United States  | +1     | enabled | —      |
| GB  | United Kingdom | +44    | enabled | —      |
| DE  | Germany        | +49    | enabled | —      |
| MX  | Mexico         | +52    | enabled | —      |
| ZA  | South Africa   | +27    | enabled | —      |

Probe walk-through on the dashboard:

1. `+14155550101` → United States, **enabled** — no flag, no advisory.
2. `+913312345678` does not resolve (not a valid IN line) — Malformed; fix
   the E.164 format. A genuine Indian number resolves to **restricted**
   with the TRAI DLT citation; route it to whoever owns compliance in your
   workspace.
3. `+8613012345678` → China, **disabled** — dispatch proceeds with a
   logged advisory unless your workspace's allowlist gates it out; a block
   is your policy decision, not the matrix's.
4. A country with no matrix row (for example, a destination the curated
   matrix does not yet list) resolves to *No coverage entry resolved* —
   treat it through your own counsel; the softswitch is the final arbiter.

## 6. Per-verdict guidance

| Verdict                          | What it means                                                       | What to do                                                                                                                                                                       |
| -------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`                        | Destination ranks no condition.                                     | Proceed; matches workspace default.                                                                                                                                              |
| `restricted`                     | The destination's regulator cites a condition.                      | Route to the person who owns compliance; keep or carve the destination per your workspace policy and record the decision.                                                        |
| `disabled`                       | Unreachable by policy — sanctions or no terminating carrier.        | Treat as the destination to carve from outbound lists, unless your own compliance posture documents an exception. The platform logs an advisory; the allowlist is what enforces. |
| `country_not_in_matrix`          | Number parses, but no matrix row. Soft warn; softswitch arbitrates. | Verify through your own counsel; flags move as regulators update their rules.                                                                                                    |
| `destination_country_unresolved` | Dial string failed E.164 parsing.                                   | Fix the number format (E.164 with `+`; the parser tolerates common formats) before dispatch.                                                                                     |

## 7. Handling violations

When a destination your workspace gates out lands on an outbound list
anyway:

1. **Throttle.** Slow the campaign or dialer while you correct the list —
   a gated-out destination still consumes attempts until the list is
   clean.
2. **Disable** the violating dispatch path — remove the destination from
   the active list; the scrub in section 4 takes seconds compared to an
   advisory-then-delete loop.
3. **Re-verify.** Run the dashboard probe (or re-pull the coverage API)
   per destination and confirm the verdict your policy expects; review the
   workspace's structured coverage-advisory log lines so the next
   violation surfaces at dispatch time.

Because the coverage verdicts and the allowlist are both tenant-scoped,
violations route to your own policy, not to a platform-wide gate.

<Note>
  Every control on this page is tenant-owned. The coverage verdicts are
  reference data; the enforcement lives in your workspace's country
  allowlist and the rest of your compliance configuration. All outbound
  calls still egress over the Devotel wholesale softswitch — nothing on
  this page steers carriers.
</Note>

## Related

* [Outbound country coverage matrix for agents](/guides/agent-outbound-country-coverage) — the same read framed for AI-agent setup, with the pre-clearance workflow
* [Tenancy posture — outbound country allowlist](/compliance/posture-overview) — the allowlist endpoint this guide pairs with
* [Launch an outbound dialer campaign](/guides/outbound-dialer-campaign) — coverage verdicts apply to dialer destinations the same way
* [Country requirements](/compliance/country-requirements) — tenant-owned per-country controls