Search companies
GET https://api.companylens.io/v1/companies/searchSearch for companies by name, or browse by structured filters — status, entity type, and incorporation date — across 19 jurisdictions. The q parameter matches company names only; it does not filter by SIC or NACE code. The searchMode parameter controls name matching: exact (default) matches the exact normalised name, automatically handling common abbreviations ("Ltd" / "Limited"); prefix matches names that start with your query and is recommended for due-diligence workflows.
Use this endpoint to build company lookup UI, power autocomplete fields, find entities before fetching their full profile, or browse companies in a sector without a name query. For exact lookups by company number, use Get company instead.
Request
Authentication
Authorization: Bearer YOUR_API_KEYParameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| q | string | no* | — | Company name to search. Min 2 characters. Matching behaviour controlled by searchMode. Does not match by industry code. Required unless at least one other filter is provided. |
| jurisdiction | string | no | *(all)* | Filter to a single jurisdiction. ISO 3166-1 alpha-2 codes (gb, fr, de). See supported jurisdictions. |
| status | string | no | all | Filter by status: active | dissolved | all |
| searchMode | string | no | exact | Matching strategy: exact — exact normalised name match (default); prefix — starts-with match using a btree index, recommended for due-diligence workflows. |
| page | integer | no | 1 | Page number, 1-indexed. |
| pageSize | integer | no | 20 | Results per page. Maximum: 100. |
Examples
curl -G https://api.companylens.io/v1/companies/search \
-H "Authorization: Bearer YOUR_API_KEY" \
--data-urlencode "q=Revolut" \
--data-urlencode "jurisdiction=gb" \
--data-urlencode "status=active"const res = await fetch(
'https://api.companylens.io/v1/companies/search?' +
new URLSearchParams({ q: 'Revolut', jurisdiction: 'uk', status: 'active' }),
{ headers: { Authorization: 'Bearer YOUR_API_KEY' } }
);
const data = await res.json();import httpx
r = httpx.get(
'https://api.companylens.io/v1/companies/search',
params={'q': 'Revolut', 'jurisdiction': 'uk', 'status': 'active'},
headers={'Authorization': 'Bearer YOUR_API_KEY'},
)
data = r.json()Response
200 — Success
{
"results": [
{
"entityId": "uk-08804411",
"entityName": "Revolut Ltd",
"jurisdiction": "uk",
"status": "active",
"incorporationDate": "2015-07-23",
"dissolutionDate": null,
"address": {
"line1": "7 Westferry Circus",
"line2": "Canary Wharf",
"city": "London",
"postcode": "E14 4HD",
"country": "GB"
},
"industryCodes": ["K6419"],
"ticker": null
}
],
"pagination": {
"page": 1,
"pageSize": 20,
"total": 3,
"hasMore": false
}
}Response fields
| Field | Type | Always present | Description |
|---|---|---|---|
| entityId | string | yes | Stable unique identifier. Format: {jurisdiction}-{registry-number} |
| entityName | string | yes | Official registered name as it appears in the source registry. |
| jurisdiction | string | yes | ISO code of the registry this record comes from. |
| status | string | yes | active | dissolved | unknown |
| incorporationDate | string (ISO 8601) | no | null if not recorded in the source registry. |
| dissolutionDate | string (ISO 8601) | no | null for active entities. |
| address | object | no | Registered address. null if the registry doesn't publish addresses. |
| industryCodes | string[] | no | NACE or SIC codes depending on jurisdiction. Empty array if unavailable. |
| ticker | string | no | Stock ticker if listed. null for private entities. |
| pagination.total | integer | yes | Total matching results across all pages. |
| pagination.hasMore | boolean | yes | Whether additional pages exist. Increment page and request again if true. |
Error responses
| HTTP status | Code | When it happens |
|---|---|---|
| 400 | INVALID_PARAMETER | q is under 2 characters; searchMode is not a recognised value; pageSize exceeds 100; no query and no filters provided |
| 400 | INVALID_JURISDICTION | Jurisdiction code not in the supported list |
| 401 | UNAUTHORIZED | API key is missing, malformed, or revoked |
| 429 | RATE_LIMITED | Monthly or daily quota exceeded — see rate limits |
Jurisdiction support
This endpoint searches all jurisdictions by default. The richness of results varies by registry:
| Field | GB | FR | DE | EE | LV | Others |
|---|---|---|---|---|---|---|
| entityName | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| status | ✓ | ✓ | ✓ | ✓ | ✓ | Varies |
| incorporationDate | ✓ | ✓ | ✓ | ✓ | ✓ | Varies |
| address | ✓ | ✓ | — | ✓ | ✓ | Varies |
| industryCodes | ✓ | ✓ | — | — | — | — |
Full coverage matrix: Jurisdictions & coverage →
Common mistakes
Using search to look up a known entity number
The q parameter is name matching only. If you have a registration number (e.g. 08804411 for Revolut Ltd), use Get company directly — it's exact, faster, and won't return unrelated results.
Using q to search by industry
q matches company names only. A query of q=accountants will not return companies unless they have "accountants" in their registered name — it won't match SIC 69201. This endpoint does not support filtering by industry code; the industryCodes field is returned for display only.
Not filtering by jurisdiction in single-market products
Without jurisdiction, search queries all 19 registries. A search for “Apple” returns hundreds of results from every jurisdiction. If your product is UK-only, always pass jurisdiction=gb.
Expecting consistent address and incorporationDate
Some registries don't publish addresses or dates. Always handle null for these fields. Check the coverage table above before relying on them in your logic.
Using pageSize: 100 to get "all results"
If pagination.total exceeds pageSize, you need to paginate. Always check hasMore — never assume the first page is complete.