---
title: "Search for companies by name"
method: GET
path: "/v1/search"
tags: ["Search"]
---

# Search for companies by name

`GET /v1/search`

## Request

- Base URL: `https://api.registrum.co.uk`
- URL: `https://api.registrum.co.uk/v1/search`
- Auth: API key in header `X-API-Key`

Search for UK companies by name.

Returns a list of matching companies with basic details. Results are cached for 1 hour.

**Example:** `/v1/search?q=tesco` returns Tesco PLC, Tesco Stores Limited, etc.

**With enrichment:** `/v1/search?q=tesco&enrich=true` also includes company age,
accounts status, and size classification for each result (capped at 10 enriched results).

---

**Upstream usage:** 1 upstream call per unique search query (cached for 1 hour).
Repeating the same query within the hour is free - no upstream call is made.
At high volume, you can safely issue ~100 unique searches per minute before
responses begin to slow. Beyond that, requests queue briefly (typically a few seconds)
while upstream capacity recovers.

## Query parameters

- `q` string, required: Company name to search for. Supports partial/fuzzy matching. A blank value returns no results with a `warning`, free of charge, rather than an error - so one empty cell cannot fail a whole batch run.
- `items_per_page` integer: Number of results to return per page (1-100).
- `start_index` integer: Offset for pagination. Use 0 for the first page, 20 for the second (if items_per_page=20), etc.
- `enrich` boolean: If true, returns full enriched profiles for each result instead of basic search data. Uses more API credits (1 per enriched result, capped at 10).

## Response `200`

Search results returned successfully

- SearchEnvelope: Response envelope for GET /v1/search.
  - `status` string: 'success' or 'error'
  - `data` SearchResponse: Paginated search results.
    - `query` string, required: The search query that was used
    - `total_results` integer: Total number of matching companies
    - `items_per_page` integer: Number of results per page
    - `start_index` integer: Offset of the first result in this page
    - `items` SearchResult[]: List of matching companies
      - `company_number` string, required: 8-character Companies House number
      - `company_name` string, required: Official registered company name
      - `company_status` string, nullable: Current status: 'active', 'dissolved', etc.
      - `company_type` string, nullable: Legal type: 'ltd', 'plc', etc.
      - `date_of_creation` string, date, nullable: Incorporation date
      - `registered_office_address` Address: A UK registered office address.
        - `premises` string, nullable: Building name or number
        - `address_line_1` string, nullable: Street address
        - `address_line_2` string, nullable: Additional address line
        - `locality` string, nullable: Town or city
        - `region` string, nullable: County or region
        - `postal_code` string, nullable: UK postcode
        - `country` string, nullable: Country
      - `snippet` string, nullable: Search relevance snippet with matched terms
    - `warning` string, nullable: Set when the query could not be run as given (e.g. a blank `q`); the results are empty and no credit was charged. Null on a normal search.
  - `cached` boolean: True if this response was served from cache rather than fetched live
  - `cache_age_seconds` integer, nullable: How many seconds ago this data was fetched from Companies House (null if not cached)
  - `fetched_at` string, nullable: ISO 8601 instant (UTC) when this data was actually fetched from Companies House. Use this, not cache_age_seconds, to show a user when the data was last checked: an age is measured at the moment this response was produced, so anything that caches the response downstream will overstate freshness by however long it held it. This instant does not drift. Null when unknown - render nothing rather than a guessed date.
  - `data_source` string: 'live' - fetched from Companies House right now; 'cached' - served from local cache (data is recent, no upstream call needed); 'cached_rate_conserved' - served from cache because the CH API budget is above 70% utilisation; data may be up to 30 days old in this state
  - `credits_used` integer: Number of API credits consumed by this request
  - `credits_remaining` integer, nullable: API credits remaining this month (null in dev mode)

## Other responses

- `401`: Missing or invalid API key
- `422`: Validation error (e.g., query too long or missing)
- `502`: Companies House API is temporarily unavailable
- `503`: Request shed to protect shared Companies House capacity; retry after the seconds given in the Retry-After header

---

[API](https://skmtc.dev/registrum/apis/registrum-api.md) · [All operations](https://skmtc.dev/registrum/apis/registrum-api/llms.txt) · [OpenAPI document](https://skmtc.dev/registrum/apis/registrum-api/revisions/2bf0ecf7cc02?raw)