Skip to main content

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

​
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. 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:
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.

​
Who can trigger a refresh

The country-rules table is one shared record: every workspace reads the same rows, so a write from any single workspace would rewrite the regulatory picture every other workspace sees. For that reason, reading the table and refreshing it are separate permissions, and the refresh side is held at the platform level. Read access is unaffected by refresh permission. Every authenticated member of your workspace sees the same rules, the same provenance stamps, and the same summary counts. Nothing in the refresh permission model hides or filters the table from a reader. Roles that cannot refresh see no refresh UI. On page load the dashboard reads the server-authored can_sync flag on the country-rules response and renders the refresh buttons only when it is true. If your role cannot refresh, the controls are simply absent: where a refresh would otherwise be offered, the page notes that the rules are populated from upstream sources on the platform side and to check back after the next scheduled refresh. There is no disabled button to puzzle over. Unauthorized mutations return a plain-language 403. The hidden UI is not the only boundary: the sync and row-update endpoints enforce the same permission server-side, so a direct API call from a session that cannot refresh fails with HTTP 403. A tenant owner or admin session receives a plain-language message of the shape “You don’t have permission to refresh this data source.” (row updates read “You don’t have permission to update country rules.”); sessions below owner or admin are refused at the workspace role gate with a 403 as well. The wording is deliberate: it names the denial without disclosing which upstream source, credential, or platform check sits behind the data source. If you receive it, read it as “this account is not the one that refreshes this table”, not as an outage or a missing credential on your side. Your read access is unaffected, and the weekly scheduled refresh keeps running. The tenant-owned layer stays tenant-owned. Refresh permission governs only the platform-maintained structural fields. The editorial guarantees above hold no matter who triggers the refresh: free-text policy columns are never overwritten, registration levels only move upward, and existing source links are preserved. This split mirrors the platform-wide access model: workspace roles gate your tenant’s data and settings, while a small set of platform-maintained records sits beside them. For the access-control evidence trail this model produces, see Access lifecycle audit evidence; for the map of which controls are tenant-owned versus platform-maintained, see the posture overview.

​
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: 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.
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.