Skip to content
iGregulator docs

Licence detail by id

GET
/v1/licenses/{license_id}

Returns a single licence by its iGregulator-assigned UUID (not the human-readable licence number). Includes the owning operator’s slug + display name and a single-resource _meta envelope with scraped_at, source_url, and confidence_hint. Call this when you want a pinnable, deep-linkable detail page for exactly one licence record.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
license_id
required
string format: uuid

Query Parameters

Section titled “Query Parameters ”
as_of
string

Point-in-time lookup. Adds an as_of object reconstructing this licence’s status within our observation window (the iron rule: never extrapolated before tracking_since). Bare YYYY-MM-DD = end of day UTC; ISO datetime supported; a future value 400s.

Example
2026-03-01

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Licence + provenance.

License with single-resource provenance _meta. Used by /v1/licenses/:license_id.

object
id
string format: uuid
license_number
string
jurisdiction_code
string
status
string
Allowed values: active suspended revoked expired pending
license_types

Multi-valued type vocabulary, sourced verbatim from the regulator. Stable values per jurisdiction (audited 2026-04-21):

  • UKGC — Remote, Non-Remote, Ancillary Remote
  • MGA — Type 1, Type 2, Type 3, Type 4, B2B, B2C
  • CW (Curaçao) — B2C, B2B
  • KH (Kahnawake) — Interactive Gaming Permit, CSPA
  • AN (Anjouan) — B2C, B2B, White Labeling
  • TGC (Tobique) — B2C, B2B

Add a new value to your client mapping when a regulator publishes one — we don’t reject unknown strings. Multi-jurisdiction operators carry one license row per jurisdiction, so this array is per-licence.

Array<string>
license_type_raw
string
license_category

Cross-jurisdiction harmonised category — derived by @igregulator/normalizer so a multi-regulator query can group by it. UKGC Remote, MGA Type 1/2, CW B2C map to remote; UKGC Non-Remote to non-remote; etc.

string
Allowed values: remote non-remote ancillary permit other
issued_date
string | null format: date
expiry_date
string | null format: date
last_verified_at
string format: date-time
source_url
string format: uri
raw_data

Scraper-specific fields captured verbatim from the upstream register (e.g. UKGC activity categories, CGA company-type flags). Not a stable integration surface. Keys here are added, renamed, or removed without a deprecation window when a scraper is updated — they do not carry the 90-day Sunset guarantee that top-level fields do. Use license_types, license_category, status, issued_date, expiry_date for stable compliance logic; read raw_data only for diagnostic / investigative purposes.

object
key
additional properties
any
as_of

Point-in-time status, present only when ?as_of= was supplied. Answers ONLY within the observation window: we never extrapolate a status before tracking_since (the first time we recorded the licence).

object
as_of
required

The resolved instant (UTC). Bare YYYY-MM-DD inputs resolve to end-of-day.

string format: date-time
knowledge
required

observed: the date is within our window, status is known. before_tracking: the date predates when we started watching — status is null, NOT a guess. no_such_license: we have no history for this licence. no_license_resolved: a fuzzy /v1/check match with no specific licence to time-travel.

string
Allowed values: observed before_tracking no_such_license no_license_resolved
status_as_of
required

Licence status as of the date, or null when not observed.

string | null
established_by
required

The history transition in effect at the date — when this status was last confirmed relative to the query.

object
changed_at
string format: date-time
new_status
string
change_type
string
source_url
string
tracking_since
required

Lower bound of our knowledge — when we first observed this licence.

string | null format: date-time
operator_id
required
string format: uuid
operator_slug
required
string
operator_name
required
string
confidence_score
number
_meta
required

Single-resource provenance envelope — answers “where did this come from and how fresh is it?” for one record.

object
scraped_at
required

ISO-8601 timestamp when iGregulator’s scraper last fetched this record.

string format: date-time
source_modified_at
required

ISO-8601 timestamp when the regulator updated the data on their register, not when our scraper fetched it. Always null today across every jurisdiction — our schema doesn’t persist per-record upstream modification time. Will populate for UKGC (the one regulator that exposes it via the ZIP’s last_updated field) once the scraper migration lands; remains null for MGA, CGA, KGC (no upstream timestamp).

string | null format: date-time
source_url
required

URL of the source register page or dump. Null when not attributable to a single URL.

string | null format: uri
confidence_hint
required

authoritative — direct from an official regulator dump (e.g. UKGC ZIP). scraped — parsed from regulator HTML/PDF (MGA, CGA, KGC). derived — computed match, not a direct lookup (fuzzy match on /v1/check, no direct source row).

string
Allowed values: authoritative scraped derived 
{
  "scraped_at": "2026-04-19T03:00:00Z",
  "source_modified_at": null,
  "source_url": "https://www.gamblingcommission.gov.uk/downloads/business-licence-data.zip",
  "confidence_hint": "authoritative"
}

401

Section titled “401 ”

Missing / malformed / revoked API key.

object
error
required

Human-readable error summary.

string
code
required

HTTP-status-level class. Stable enum; branch on details.reason for finer control. Current values: invalid_query, invalid_slug, invalid_license_id, invalid_jurisdiction_code, invalid_pagination, not_found, auth_required, auth_invalid, auth_revoked, payment_required, quota_exceeded, rate_limited, server_error.

string
details
required
object
reason
required

Machine-readable refinement of the top-level code. Stable vocabulary; branch on this in clients. Examples: invalid_input, missing_required_parameter, conflicting_parameters, operator_not_found, license_not_found, jurisdiction_not_found, route_not_found, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, quota_exceeded, internal_error.

string
field

Present only when the error maps to a specific request input field (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).

string
suggestion

Optional human-readable / agent-actionable hint describing how to resolve the error.

string
{
  "reason": "api_key_revoked",
  "suggestion": "Generate a new API key at https://app.igregulator.io/settings. Revoked keys cannot be restored."
}
{
  "error": "API key has been revoked",
  "code": "auth_revoked",
  "details": {
    "reason": "api_key_revoked",
    "suggestion": "Generate a new API key at https://app.igregulator.io/settings. Revoked keys cannot be restored."
  }
}

404

Section titled “404 ”

No row matched.

object
error
required

Human-readable error summary.

string
code
required

HTTP-status-level class. Stable enum; branch on details.reason for finer control. Current values: invalid_query, invalid_slug, invalid_license_id, invalid_jurisdiction_code, invalid_pagination, not_found, auth_required, auth_invalid, auth_revoked, payment_required, quota_exceeded, rate_limited, server_error.

string
details
required
object
reason
required

Machine-readable refinement of the top-level code. Stable vocabulary; branch on this in clients. Examples: invalid_input, missing_required_parameter, conflicting_parameters, operator_not_found, license_not_found, jurisdiction_not_found, route_not_found, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, quota_exceeded, internal_error.

string
field

Present only when the error maps to a specific request input field (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).

string
suggestion

Optional human-readable / agent-actionable hint describing how to resolve the error.

string
{
  "reason": "api_key_revoked",
  "suggestion": "Generate a new API key at https://app.igregulator.io/settings. Revoked keys cannot be restored."
}
{
  "error": "API key has been revoked",
  "code": "auth_revoked",
  "details": {
    "reason": "api_key_revoked",
    "suggestion": "Generate a new API key at https://app.igregulator.io/settings. Revoked keys cannot be restored."
  }
}

500

Section titled “500 ”

Unexpected server error.

object
error
required

Human-readable error summary.

string
code
required

HTTP-status-level class. Stable enum; branch on details.reason for finer control. Current values: invalid_query, invalid_slug, invalid_license_id, invalid_jurisdiction_code, invalid_pagination, not_found, auth_required, auth_invalid, auth_revoked, payment_required, quota_exceeded, rate_limited, server_error.

string
details
required
object
reason
required

Machine-readable refinement of the top-level code. Stable vocabulary; branch on this in clients. Examples: invalid_input, missing_required_parameter, conflicting_parameters, operator_not_found, license_not_found, jurisdiction_not_found, route_not_found, api_key_missing, malformed_header, api_key_invalid, api_key_revoked, quota_exceeded, internal_error.

string
field

Present only when the error maps to a specific request input field (query param, path param, body key). Omitted for errors that aren’t field-scoped (e.g. rate_limited, auth_revoked).

string
suggestion

Optional human-readable / agent-actionable hint describing how to resolve the error.

string
{
  "reason": "api_key_revoked",
  "suggestion": "Generate a new API key at https://app.igregulator.io/settings. Revoked keys cannot be restored."
}
{
  "error": "API key has been revoked",
  "code": "auth_revoked",
  "details": {
    "reason": "api_key_revoked",
    "suggestion": "Generate a new API key at https://app.igregulator.io/settings. Revoked keys cannot be restored."
  }
}