Point-in-time lookups (as_of)

iGregulator keeps the transition history of every licence, so you can ask “what was this operator’s status on date X” — the question a compliance review asks constantly (“was this merchant licensed at the time of the transaction three months ago?”) and the one no incumbent can answer, because none keeps the history.

Pass ?as_of= to /v1/check, /v1/licenses/{id}, or /v1/operators/{slug}.

The one rule that matters

as_of answers only within our observation window. We never extrapolate a status before tracking_since — the moment we first recorded the licence.

Our history begins when our scraper first saw a record (change_type: "created"). We do not know what was true before that, so we never guess. Asking about a date before tracking_since returns knowledge: "before_tracking" with a null status — not a fabricated “active”. A tool that invented pre-observation history would force you to assert a historical fact the data never witnessed; that is worse than not having the feature.

iGregulator answers “as of date X” only within its observation window — it tells you when it started watching, and never invents a status it didn’t observe.

The three states of knowledge

knowledge	When	status_as_of
observed	The date is within our window (≥ tracking_since).	The real status then.
before_tracking	The date predates when we started watching.	null — unknowable, not a guess. tracking_since tells you the lower bound.
no_such_license	We have no history for this licence at all.	null.
no_license_resolved	(/v1/check only) A fuzzy match with no specific licence to time-travel.	null.

The as_of object also returns established_by — the exact history transition in effect on your date (changed_at, new_status, change_type, source_url) — so you can see when that status was last confirmed relative to your query.

Date semantics

• A bare YYYY-MM-DD is interpreted as end of that day, UTC (status at close of day).
• A full ISO-8601 datetime is honoured as given.
• A date in the future returns 400 — we never answer about a date we haven’t observed. It is never silently clamped to “now”.

Examples

before_tracking — asking before we started watching:

// GET /v1/licenses/140a822c-…?as_of=2026-01-01
{
  "as_of": "2026-01-01T23:59:59.999Z",
  "knowledge": "before_tracking",
  "status_as_of": null,
  "established_by": null,
  "tracking_since": "2026-04-17T15:15:40.055Z"
}

observed — a date after a revocation transition:

// GET /v1/licenses/140a822c-…?as_of=2026-05-20
{
  "as_of": "2026-05-20T23:59:59.999Z",
  "knowledge": "observed",
  "status_as_of": "revoked",
  "established_by": {
    "changed_at": "2026-05-13T01:00:05.215Z",
    "new_status": "revoked",
    "change_type": "status_change",
    "source_url": "https://www.gamblingcommission.gov.uk/downloads/business-licence-data.zip"
  },
  "tracking_since": "2026-04-17T15:15:40.055Z"
}

Endpoint notes

• /v1/licenses/{id}?as_of= — cleanest: one licence, one as_of object.
• /v1/operators/{slug}?as_of= — resolved per licence (each licence in the array gets its own as_of); we don’t collapse a multi-jurisdiction operator into a single status — you aggregate as your policy requires.
• /v1/check?domain=X&as_of= — the domain→operator attribution is taken as current; only the licence status is time-travelled. Historical domain attribution (we keep first_seen on domains) is a future addition.