Jurisdictions
Every search and profile lookup is scoped to a jurisdiction — the country whose
official company register the data comes from. You supply it as an
ISO 3166-1 alpha-2 code in the
jurisdiction query parameter.
Supported jurisdictions
| Code | Jurisdiction | Source register |
|---|---|---|
GB |
United Kingdom | Companies House |
IE |
Ireland | Companies Registration Office (CRO) |
GB and IE are the jurisdictions with company data today. The jurisdiction
parameter accepts any valid ISO 3166-1 alpha-2 code syntactically, but only GB and IE
return results — others will simply find nothing.
Where it's used
The jurisdiction parameter is required on both data endpoints:
# Search within Great Britain
curl -H "Authorization: Bearer $TOKEN" \
"https://public-api.heygrand.com/v1/search?q=Acme&jurisdiction=GB"
# Fetch an Irish company profile
curl -H "Authorization: Bearer $TOKEN" \
"https://public-api.heygrand.com/v1/profile/123456?jurisdiction=IE"
A company number is only unique within a jurisdiction, so you must pass the same
jurisdiction to /v1/profile that you used when you found the company via /v1/search.
What differs by jurisdiction
- Registration number format. UK (GB) numbers are typically 8 characters; Irish (IE) numbers are shorter and numeric. Always treat the number as an opaque string — don't assume a fixed length or pad it.
-
Trading status vocabulary. The
status/tradingStatusvalues reflect the source register's own terminology and may differ between GB and IE.
Invalid jurisdiction
An unrecognised code returns 400 Bad Request:
{ "message": "Unknown jurisdiction: ZZ" }
See Errors & status codes for how to handle this.