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

# Country Rules Auto-Refresh Feeds

> How the country-rules table stays current: the upstream feeds that refresh it, the editorial columns a refresh never overwrites, the provenance stamp on every row, and how to enable credentials and check sync health.

# Country Rules Auto-Refresh Feeds

The per-country, per-channel rules that the messaging compliance gates
read are not a static snapshot. Orbit refreshes the rules table from
upstream regulatory feeds so the sender-type list, the registration
level, and the regulator source link on each row track what the
registries actually publish — without ever overwriting the policy text
your team has written into a row.

This page explains what the refresh does, what it can and cannot
change, how to trace why a row changed, and how to turn each feed on.

<Note>
  The refresh maintains the **structural** fields of each row
  (country name, calling code, region, sender types, registration
  level, source links). The legal posture for each destination is
  still yours — this page documents the maintenance mechanism, not
  legal advice.
</Note>

***

## What the auto-refresh does

Each refresh connector pulls one authoritative upstream registry and
upserts what it finds into the country-rules table — the same table
returned by `GET /api/v1/compliance/country-rules` and rendered on the
country-rules dashboard. There are six feeds, and each one is
independent: enabling or disabling one never affects the others.

| Feed                                  | What it contributes                                                                                                        | Cost                          |
| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| **MEF SenderID Protection Registry**  | MNO-signed per-country sender-ID rules — registration level, permitted sender types, regulator link                        | Paid registry membership      |
| **GSMA SMS Hub sender-ID protection** | Companion sender-ID registry to MEF — registration level, sender types, regulator link                                     | Member portal                 |
| **GSMA Network Codes**                | Structural identity fields — country name, calling code, region                                                            | Member portal                 |
| **iconectiv TCR (US 10DLC)**          | The canonical US 10DLC ruleset — sender types, throughput posture, registration requirement                                | Free for registered partners  |
| **Meta Business API (WhatsApp)**      | Per-country WhatsApp Business availability — stamps the WhatsApp sender type on countries that can host a business account | Free with a system-user token |
| **ITU WTID**                          | National-regulator URLs mirrored into the row's source links                                                               | Free (attribution required)   |

Two properties hold across every feed:

1. **Upsert, not scrape-and-replace.** A refresh updates the rows the
   upstream reports on; it never deletes rows the upstream stops
   mentioning, so a feed that silently shrinks cannot wipe coverage.
2. **The country code is validated.** A row only lands when the
   upstream reports a valid two-letter country code, so malformed feed
   entries are dropped rather than written.

***

## What a refresh never overwrites

The feeds exist to keep structural data fresh. They are deliberately
blocked from touching the editorial layer — the policy text your team
writes and reviews:

* **Free-text columns are never touched.** Sender rules, content
  restrictions, opt-out requirements, and notes are entirely absent
  from every refresh write. A feed leaves them at their existing value
  — forever — so an automated pull can never erase curated policy.
* **Registration only upgrades.** A feed can move a row's registration
  level upward (`none` → `recommended` → `required`) but never
  downward. A registry going quiet about a country cannot silently
  downgrade a posture your team asserted as `required`.
* **Source links are fill-if-blank.** A feed adds regulator source
  links only to a row that has none. Any links already on the row are
  preserved as-is.
* **Structural fields are fill-if-empty.** Country name, calling code,
  and region refresh only when the upstream reports a non-empty value
  — a partially populated feed response cannot blank an existing field.

Manual edits and automatic refreshes coexist by design: your edits own
the editorial columns, the feeds keep the structural fields current.

***

## Provenance: tracing why a row changed

Every row carries a provenance stamp you can read straight off the
API response or the dashboard:

* **`sync_source`** — which origin last touched the row: one of the
  feed names above, or `manual` for an ops edit.
* **`last_synced_at`** — when the last automatic refresh touched the
  row.
* **`last_reviewed_at`** — when the last manual edit landed.

The country-rules response surfaces this per row, and its summary
counts tell you how much of the table is feed-refreshed versus
human-reviewed. To audit why a specific row changed, compare
`sync_source` and the two timestamps against the cadence below — a row
whose `sync_source` is a feed and whose `last_synced_at` roughly
matches the weekly cadence was updated by that feed.

***

## Fail-open posture

A dead upstream never takes the refresh down. Each feed reports its
outcome — how many entries the upstream returned, how many rows were
created or updated, and any errors — rather than throwing. A missing
credential, a timeout, or a malformed payload lands in that error
list, the failing feed is skipped, and every other feed still runs.

For you this means:

* A feed with no credentials configured is **skipped cleanly** — it
  does not block the refresh and does not corrupt the table.
* A feed outage leaves your existing rows in place. The next
  successful refresh catches up; nothing is deleted in the meantime.
* The on-demand refresh response always comes back with per-feed
  counts and error messages, so you can see exactly which feeds
  succeeded and which need attention.

***

## The two trigger surfaces

The same refresh implementation runs from two places — an on-demand
pull and a weekly automatic pass — so a manual refresh and the
scheduled one can never drift apart in behavior.

**On-demand (admin refresh).** A Devotel platform admin can pull one
feed immediately through the country-rules sync endpoint:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/country-rules/sync?provider=mef&channel=sms" \
  -H "Authorization: Bearer $ORBIT_API_KEY"
```

`provider` is one of `telnyx`, `mef`, `gsma`, `iconectiv`, `meta`, or
`itu`; `channel` is one of `sms`, `whatsapp`, `rcs`, `voice`, `email`,
or `viber`. The response reports entries read, rows created, rows
updated, and any per-feed errors. This endpoint is platform-admin
only — the table is a global regulatory record every tenant reads, so
mass-refreshing it is not a tenant-level action.

**Weekly scheduler.** All configured feeds run automatically on a
weekly cadence. Feeds without credentials self-skip, so the tick is a
no-op for anything you have not enabled.

***

## Enable credentials and check sync health

Each feed activates the moment its credential is present in the
environment — there is no second switch to flip. Set the variables for
the feeds you subscribe to:

| Feed                     | Environment variables                                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| MEF SenderID Registry    | `DEVOTEL_MEF_API_KEY` (optional `DEVOTEL_MEF_FEED_URL` to override the base URL)                                 |
| GSMA registries          | `DEVOTEL_GSMA_API_KEY` (optional `DEVOTEL_GSMA_FEED_URL`)                                                        |
| iconectiv TCR (US 10DLC) | `DEVOTEL_TCR_API_KEY` + `DEVOTEL_TCR_PARTNER_ID` (optional `DEVOTEL_TCR_FEED_URL`)                               |
| Meta WhatsApp coverage   | `DEVOTEL_META_GRAPH_TOKEN` (falls back to your WhatsApp access token; optional `DEVOTEL_META_WABA_COVERAGE_URL`) |
| ITU WTID                 | `DEVOTEL_ITU_WTID_URL` (public dataset — no key)                                                                 |

To check sync health:

1. **Read the summary on the country-rules response** — the most
   recent refresh timestamp, the count of feed-synced rows, and the
   count of human-reviewed rows. A stale timestamp on a feed you
   expect to run weekly means that feed is failing.
2. **Run the admin sync endpoint for one provider** and inspect the
   per-feed errors — a missing credential is reported by name, an
   upstream outage by status, so the fix is usually unambiguous.
3. **Watch row provenance** — rows a feed owns carry that feed's
   `sync_source` and a `last_synced_at` close to the weekly cadence.
   Rows that stop updating while their errors accumulate point at the
   failing upstream.

<Note>
  These feeds only read regulatory metadata. They never route outbound
  voice or messaging traffic — sending stays with the Devotel
  softswitch, exactly as it does everywhere else on the platform.
</Note>

***

## Related references

* [Country Compliance Requirements](/compliance/country-requirements) —
  the live per-country, per-channel rules reference the feeds maintain.
* [Regional Posture Hub](/compliance/country-rules-directory) — the
  index over every per-country deep-dive page.
* [Sender-ID Registration](/compliance/sender-id-registration) — file
  a sender registration where a refreshed row raises its level.
* [Send Gates](/compliance/send-gates) — the send-time enforcement
  points these rules feed.