---
title: "Search companies"
method: GET
path: "/company/search"
tags: ["Companies"]
---

# Search companies

`GET /company/search`

## Request

- Base URL: `https://api.companystack.co.uk`
- URL: `https://api.companystack.co.uk/company/search`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Full-text search across about 6 million UK companies. Give at least one of q, status, sic, postcode or town; filters combine with AND.

Free plan: only the first page is available. At most 10 results are returned and `offset` is not applied (the response reports `offset: 0`), so a loop that pages until it gets an empty page never ends: stop when a page holds fewer results than `limit`, or when `paging_limited` is true. When the plan limits paging, the response carries `paging_limited: true`, the ignored `requested_offset`, a plain-sentence `notice` and an `upgrade_url`. Paid plans return up to 100 results per page and page with `offset`.

## Query parameters

- `q` string
- `status` string
- `sic` string
- `postcode` string
- `town` string
- `limit` integer
- `offset` integer
- `incorporated_from` string, date
- `incorporated_to` string, date

## Response `200`

Search results with total count

- CompanySearchResult
  - `total` integer, required: Matching companies (capped for very broad filters; see total_capped)
  - `total_capped` boolean
  - `limit` integer, required: Results per page as applied (at most 10 on the Free plan)
  - `offset` integer, required: The offset applied. Always 0 on the Free plan, which returns only the first page whatever offset was requested
  - `paging_limited` boolean: Present (true) when the plan returns only the first results: more matches exist than were returned, or the offset asked for was ignored
  - `requested_offset` integer: The offset that was asked for and ignored (with paging_limited)
  - `notice` string: A plain sentence explaining the paging limit (with paging_limited)
  - `upgrade_url` string, uri: Where to lift the paging limit (with paging_limited)
  - `query` string
  - `results` Company[], required
    - `company_number` string, required: 8 characters, e.g. 00445790 or SC586124
    - `company_name` string, required
    - `company_status` string, required: e.g. active, dissolved, liquidation
    - `company_type` string
    - `date_of_creation` string, date
    - `dissolution_date` string, date
    - `registered_office_address` string: The registered office as one comma-separated line
    - `registrar_default_address` object: Present only when Companies House has removed the company's registered office and put it at the registrar's default address (PO Box 4385, Cardiff CF14 8LH; PO Box 24238, Edinburgh EH7 9HR; or BT1 9DY, Belfast). The address above is then that default address, not the company's own.
      - `at_default_address` true, required
      - `statement` string, required
      - `changed_on` string, date, nullable, required: The day Companies House changed the registered office, from the filing history CompanyStack holds; null when not held
    - `country_of_origin` string
    - `sic_codes` SicCode[]
      - `code` string, required
      - `description` string
    - `accounts` object
      - `next_due` string, date
      - `last_made_up_to` string, date
      - `category` string
      - `reference_day` integer
      - `reference_month` integer
      - `overdue` boolean
    - `confirmation_statement` object
      - `next_due` string, date
      - `last_made_up_to` string, date
      - `overdue` boolean
    - `mortgages` object
      - `total_count` integer
      - `outstanding_count` integer
      - `part_satisfied_count` integer
      - `satisfied_count` integer
    - `previous_names` object[]
      - `name` string
      - `changed_on` string, date
    - `data_freshness` object: How current the register entry is. as_at is the date to quote: the later of the latest monthly Companies House snapshot that listed the company and the last update from the Companies House stream or API. last_updated is when CompanyStack last rewrote the row, which an unchanged company keeps from an older snapshot.
      - `as_at` string, date: The date the register entry is known current as at (YYYY-MM-DD)
      - `last_updated` string
      - `source` string
      - `etag` string
    - `data_source` string
    - `entity_kind` 'company' | 'llp' | 'lp' | 'scottish_partnership' | 'overseas' | 'other': GET /company/{number} only. The kind of entity, decided from company_type and, only when that is missing or "Other company type", from the number prefix: company; llp (limited liability partnership); lp (limited partnership); scottish_partnership; overseas (overseas companies, UK establishments and overseas entities); other (for example charitable incorporated organisations, registered societies, royal charter bodies, ICVCs and economic interest groupings).
    - `people_term` object: GET /company/{number} only. What the people on the register are called for this kind of entity: officer and officers for a company (and for overseas and other bodies), member and members for an LLP, partner and partners for a partnership.
      - `one` string, required
      - `many` string, required
    - `limited_partnership` object: GET /company/{number} only, and only for a limited partnership whose register entry records at least one partner: the numbers of general and limited partners in Companies House's company data product.
      - `general_partners` integer, required
      - `limited_partners` integer, required

## Other responses

- `400`: No search parameter, or an invalid one
- `401`: API key missing, malformed or revoked
- `403`: `code: plan_upgrade_required`: incorporation dates reaching into the last 30 days need a plan with the New Companies feed (API Starter and above); the body gives `required_plan`, `upgrade_url` and `open_to_every_plan.incorporated_to`
- `429`: Per-minute or per-day limit reached (`code: rate_limited`, `window: minute|day`). Wait `Retry-After` seconds; when both windows are full the day is reported. A refused request does not count against either limit. A bulk lookup (`POST /company/bulk`) counts each company number in it as one request, so one that is more than you have left is refused whole, and the body adds `requested` and `fits`.

---

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