--- title: "Screen companies by their filed figures, place, age and filings" method: GET path: "/accounts/search/filter" tags: ["Intelligence"] --- # Screen companies by their filed figures, place, age and filings `GET /accounts/search/filter` ## Request - Base URL: `https://api.companystack.co.uk` - URL: `https://api.companystack.co.uk/accounts/search/filter` - Auth: one of: - HTTP bearer - API key in header `X-Api-Key` The financial screener: companies matching every filter given (AND), judged on their latest filed accounts whenever a figure is filtered or sorted on (`basis_code: accounts`), otherwise on the register with or without accounts (`register`). Give at least one filter; without one the 400 lists `filters_available`. Money is in whole pounds. Figures that fail the plausibility checks are left out unless `include_implausible=true`, and companies at mass-registration addresses unless `include_mass_registration=true`. Up to 200 rows a page, paged with offset; `total` is capped at 10,000. Needs API Starter or above. ## Query parameters - `min_turnover` number - `max_turnover` number - `min_assets` number - `max_assets` number - `min_net_assets` number - `max_net_assets` number - `min_profit` number - `max_profit` number - `min_employees` number - `max_employees` number - `min_cash` number - `max_cash` number - `min_liabilities` number - `max_liabilities` number - `min_turnover_growth` number - `max_turnover_growth` number - `min_employee_growth` number - `max_employee_growth` number - `sic_code` string - `status` string - `accounts_type` string - `region` string - `town` string - `county` string - `local_authority` string - `constituency` string - `ward` string - `msoa` string - `rural_urban` string - `imd_decile_min` number - `imd_decile_max` number - `incorporated_from` string, date - `incorporated_to` string, date - `accounts_overdue` 'true' | 'false' - `accounts_overdue_days` number - `confirmation_overdue` 'true' | 'false' - `confirmation_overdue_days` number - `gazette` string - `gazette_days` number - `insolvent` 'true' | 'false' - `net_assets_falling` 'true' | 'false' - `has_charges` 'true' | 'false' - `exclude_holding` 'true' | 'false' - `include_implausible` 'true' | 'false' - `include_mass_registration` 'true' | 'false' - `min_tangible_assets` number - `max_tangible_assets` number - `min_fixed_assets` number - `max_fixed_assets` number - `min_intangible_assets` number - `max_intangible_assets` number - `min_debtors` number - `max_debtors` number - `min_stocks` number - `max_stocks` number - `min_long_term_liabilities` number - `max_long_term_liabilities` number - `min_share_capital` number - `max_share_capital` number - `min_dividends` number - `max_dividends` number - `min_operating_profit` number - `max_operating_profit` number - `min_retained_earnings` number - `max_retained_earnings` number - `min_charges_outstanding` number - `max_charges_outstanding` number - `min_charges_total` number - `max_charges_total` number - `min_current_pscs` number - `max_current_pscs` number - `min_psc_changes_12m` number - `max_psc_changes_12m` number - `corporate_owned` 'true' | 'false' - `company_category` string - `accounts_category` string - `fields` string - `basis` 'accounts' | 'register' - `sort` 'turnover' | 'assets' | 'net_assets' | 'profit' | 'employees' | 'cash' | 'liabilities' | 'name' | 'turnover_growth' | 'employee_growth' | 'net_assets_change' | 'incorporated' | 'accounts_due' | 'confirmation_due' | 'tangible_assets' | 'fixed_assets' | 'debtors' | 'long_term_liabilities' | 'share_capital' | 'dividends' | 'operating_profit' | 'psc_changes_12m' | 'charges_outstanding' - `order` 'asc' | 'desc' - `limit` integer - `offset` integer ## Response `200` Matching companies, a page at a time - ScreenerResult - `total` integer, required: Companies matching (capped: see total_capped) - `total_capped` boolean, required - `basis` string: What each row is judged on, in words - `basis_code` 'accounts' | 'register': accounts: each company's latest filed accounts (whenever a figure is filtered or sorted on). register: every company on the register, with or without accounts. - `filters_applied` string[] - `fields` string[]: The extra column keys returned on every result (from the fields parameter); each is also a top-level key of the result rows - `notes` string[] - `results` object[], required - `company_number` string - `company_name` string, nullable - `company_status` string, nullable - `sic_code` string, nullable - `balance_sheet_date` string, date, nullable: Period end of the latest filed accounts (null on the register basis for a company without accounts) - `accounts_type` string, nullable - `turnover` integer, nullable: Turnover. Whole units of the reporting currency (GBP pounds, not pence or thousands); null when not filed. - `gross_profit` integer, nullable: Gross profit. Whole units of the reporting currency (GBP pounds, not pence or thousands); null when not filed. - `profit_before_tax` integer, nullable: Profit before tax. Whole units of the reporting currency (GBP pounds, not pence or thousands); null when not filed. - `profit_after_tax` integer, nullable: Profit after tax. Whole units of the reporting currency (GBP pounds, not pence or thousands); null when not filed. - `total_assets` integer, nullable: Total assets. Whole units of the reporting currency (GBP pounds, not pence or thousands); null when not filed. - `current_assets` integer, nullable: Current assets. Whole units of the reporting currency (GBP pounds, not pence or thousands); null when not filed. - `cash_at_bank` integer, nullable: Cash at bank. Whole units of the reporting currency (GBP pounds, not pence or thousands); null when not filed. - `current_liabilities` integer, nullable: Current liabilities. Whole units of the reporting currency (GBP pounds, not pence or thousands); null when not filed. - `total_liabilities` integer, nullable: Total liabilities. Whole units of the reporting currency (GBP pounds, not pence or thousands); null when not filed. - `net_assets` integer, nullable: Net assets (negative: net liabilities). Whole units of the reporting currency (GBP pounds, not pence or thousands); null when not filed. - `shareholder_funds` integer, nullable: Shareholder funds. Whole units of the reporting currency (GBP pounds, not pence or thousands); null when not filed. - `employees` integer, nullable - `post_town` string, nullable - `region` string, nullable - `incorporation_date` string, date, nullable - `accounts_next_due` string, date, nullable - `accounts_overdue_days` integer, nullable - `confirmation_statement_next_due` string, date, nullable - `confirmation_statement_overdue_days` integer, nullable - `outstanding_charges` integer, nullable - `latest_gazette_notice` object, nullable - `year_on_year` object, nullable - `owner_linked_insolvencies` object, nullable - `implausible_excluded` boolean: Figures that fail the plausibility checks are left out unless include_implausible=true - `limit` integer, required - `offset` integer, required - `sort` string - `order` 'ASC' | 'DESC' ## Other responses - `400`: No filter (the body lists filters_available), or an invalid one - `401`: API key missing, malformed or revoked - `403`: The key's plan does not include this endpoint (`code: plan_upgrade_required`, with `upgrade_url`), the key may not call it, or the key is beyond the plan's key limit after a downgrade (`code: key_limit_exceeded`: the newest keys are paused until keys are deleted or the plan upgraded) - `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)