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 states of knowledge

`knowledge`	When	`status_as_of`
`observed`	The date is within our window (≥ `tracking_since`).	The real status then.
`corrected`	The event in effect on that date is one we later withdrew.	`null`. We report neither the withdrawn status nor the one before it — neither is something we observed for that date. `correction` says what was withdrawn, when, and why.
`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"
}

corrected — a date inside a period we got wrong and said so:

// GET /v1/licenses/6e31e34b-…?as_of=2026-08-20
{
  "as_of": "2026-08-20T23:59:59.999Z",
  "knowledge": "corrected",
  "status_as_of": null,
  "established_by": null,
  "correction": {
    "changed_at": "2026-08-10T02:00:21.269Z",
    "withdrawn_status": "revoked",
    "corrected_at": "2026-09-17T17:20:11.123Z",
    "note": "Inferred from the licence disappearing from the register, not from a regulator publication. No regulator publication of a revocation was found."
  },
  "tracking_since": "2026-04-18T15:15:41.000Z"
}

History is never deleted here — a wrong event is marked and superseded — so the record of what we used to say is still there, and as_of must not serve it back as fact. withdrawn_status is that record; it is not the status. Until 2026-09-17 we reported licences that dropped off a register as revoked; those events are withdrawn, and a date inside one of those windows answers corrected. Treat it like before_tracking: we cannot tell you the status on that date.

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.