Reference data status

This endpoint reports the freshness of the shared number reference data: one entry per declared source, and one entry per derived collection built from those sources. Access follows one rule, and it is stricter than the admin gate used everywhere else: reads require an admin role and the platform organization. Every other caller — including an admin of a customer organization — receives 404, never 403. The 404 is deliberate: a 403 would confirm that a platform-wide reference surface exists, which is itself the disclosure. The operation is published here so that it carries a typed client, not because it is callable by a customer organization.

Method	Endpoint	Access	Success
`GET`	`/admin/reference/status`	Admin and platform organization	`200` — the status record below

The status record

{
  "sources": [
    {
      "id": "overlay_complexes",
      "cadence_seconds": 2592000,
      "mode": "scheduled",
      "last_success_at": "2026-09-08T09:04:11Z",
      "last_attempt_at": "2026-09-08T09:04:11Z",
      "age_seconds": 2246269.0,
      "status": "fresh",
      "drift": {
        "row_count_delta": 2,
        "changed_keys": 11
      }
    },
    {
      "id": "exchange_geography",
      "cadence_seconds": 2592000,
      "mode": "scheduled",
      "last_success_at": "2026-08-20T09:06:52Z",
      "last_attempt_at": "2026-10-04T09:06:48Z",
      "age_seconds": 3887708.0,
      "status": "stale",
      "drift": {
        "row_count_delta": -148,
        "changed_keys": 3104
      }
    },
    {
      "id": "zip_area_codes",
      "cadence_seconds": 31536000,
      "mode": "manual",
      "last_success_at": "2026-02-14T18:22:05Z",
      "last_attempt_at": "2026-02-14T18:22:05Z",
      "age_seconds": 20010235.0,
      "status": "fresh",
      "drift": {
        "row_count_delta": null,
        "changed_keys": null
      }
    },
    {
      "id": "us_postal_codes",
      "cadence_seconds": 31536000,
      "mode": "scheduled",
      "last_success_at": "2024-11-08T09:03:40Z",
      "last_attempt_at": "2024-11-08T09:03:40Z",
      "age_seconds": 60048500.0,
      "status": "aging",
      "drift": {
        "row_count_delta": 0,
        "changed_keys": 0
      }
    },
    {
      "id": "ca_postal_codes",
      "cadence_seconds": 31536000,
      "mode": "manual",
      "last_success_at": null,
      "last_attempt_at": null,
      "age_seconds": null,
      "status": "failed",
      "drift": {
        "row_count_delta": null,
        "changed_keys": null
      }
    }
  ],
  "collections": {
    "ref__area_codes": {
      "live_snapshot_ids": ["snp_4b1f0c7a9d2e5831"],
      "swapped_at": "2026-09-08T09:11:02Z",
      "doc_count": 800
    },
    "ref__exchanges": {
      "live_snapshot_ids": [
        "snp_4b1f0c7a9d2e5831",
        "snp_7c93ad04e15b6620"
      ],
      "swapped_at": "2026-09-08T09:19:47Z",
      "doc_count": 236045
    },
    "ref__postal_codes": {
      "live_snapshot_ids": ["snp_2e58a1d94b0c7f33"],
      "swapped_at": "2024-11-08T09:12:30Z",
      "doc_count": 33791
    }
  }
}

Two entries in that sample are worth reading together. exchange_geography is only one and a half cadences old, which on age alone would be aging — it reads stale because its most recent refresh (last_attempt_at, later than last_success_at) ran and did not install. ca_postal_codes has never loaded at all, which is failed rather than a missing entry.

Source fields

sources carries one entry per declared source, always — including a source that has never loaded. A source is never omitted, because an omitted source is one nobody notices has broken.

Field	Meaning
`id`	Stable identifier for the source, named for what it supplies: `overlay_complexes`, `exchange_geography`, `zip_area_codes`, `us_postal_codes`, `ca_postal_codes`.
`cadence_seconds`	How often this source is expected to refresh. The freshness thresholds below are multiples of this value, not fixed day counts.
`mode`	`scheduled` when the source refreshes on its own schedule; `manual` when a new release has to be supplied by an operator. A manual source still ages and still goes stale — that is how it asks for the upload.
`last_success_at`	When the newest usable data for this source was obtained. This dates the data, not the run: a refresh that succeeded by reusing the previous file does not move this timestamp. `null` when the source has never produced usable data.
`last_attempt_at`	When this source was last attempted, successfully or not. Equal to `last_success_at` on a healthy source; later than it on a source whose most recent refresh did not install.
`age_seconds`	Age of the newest usable data, in seconds. `null` when the source has never produced usable data.
`status`	`fresh`, `aging`, `stale`, or `failed` — see below.
`drift.row_count_delta`	Rows gained (positive) or lost (negative) versus the previous snapshot, summed across the files that make up the source.
`drift.changed_keys`	How many keys changed value between the previous corpus and the one currently installed.

drift’s two fields distinguish null from 0, and the distinction matters: null means unknown — there is nothing earlier to compare against, while 0 means measured, and nothing moved. Collapsing the first into the second would make a brand-new source look like a perfectly stable one.

Status vocabulary

The status is computed on the server, from the source’s own declared cadence, by the same code that drives the monitoring alerts. A source reported here as stale or failed is already alerting — this value is never only a colour.

Status	When
`fresh`	Age is within one cadence.
`aging`	Age is between one and two cadences. The boundaries are half-open at the bottom: a monthly source that is exactly a month old is already `aging`.
`stale`	Age is beyond two cadences, or the most recent refresh failed validation. A refresh that ran and did not install is not a fresh refresh, however recently it ran.
`failed`	The most recent attempt errored outright, or the source has never been attempted. `failed` wins over age.

Collection fields

collections is keyed by collection name. The key set is declared server-side and is the same on every response.

Field	Meaning
`live_snapshot_ids`	The snapshots the live corpus was built from. Empty when nothing has been installed yet.
`swapped_at`	When the live corpus was last replaced. `null` when nothing has been installed yet.
`doc_count`	How many records the live corpus holds. `null` when nothing has been installed yet.

These three fields describe the installed corpus, not the most recent attempt. A refresh that fails validation leaves the previous corpus serving untouched, so they keep describing that corpus — the failure is visible in the relevant source’s status, which is where it belongs.

Errors

The endpoint uses the standard {"detail": "..."} envelope.

Status	When
`401`	Missing or invalid credentials.
`404`	The surface is not available to this organization — returned instead of a `403`, so the answer does not depend on whether the surface exists.
`422`	The request failed validation.
`429`	Request rate limit exceeded — retry after the `Retry-After` header.

A 403 is deliberately not part of this endpoint’s documented surface.

Overview

Flows — /v1/flows

Account — /v1/account

Data — /v1/data

Catalog — /v1/catalog

Credentials — /v1/credentials

Tenants — /v1/tenants

Five9 Domains — /v1/platforms/five9

Admin — /v1/admin

The status record

Source fields

Status vocabulary

Collection fields

Errors

​The status record

​Source fields

​Status vocabulary

​Collection fields

​Errors

The status record

Source fields

Status vocabulary

Collection fields

Errors