/api/findcompanies

• POST /api/findcompanies : Paid endpoint, 1 credit per company returned.
• POST /api/findcompanies/metadata : Free count endpoint for provided filter payload (returns JSON object with count).

Billing note: Embedded companyData in the response does not consume additional credits. Billing is only 1 credit per company returned by /api/findcompanies.

The current financial filter definitions (labels, categories, and filter keys) are documented here:

Note: financialFilters[].filterName is case-insensitive.

See: /Documentation/v2/FindCompaniesMetaData.

Paging is applied server-side for this endpoint. The response contains only the requested page.

The filter keys listed below already strip taxonomy prefixes (e.g. core_, direp_, aurep_). Use the values shown (case-insensitive) for financialFilters[].filterName when building search or metadata payloads.

SIC lookup: /Documentation/v2/SicCodes.

{
  "apiVersion": "2",
  "searchTerm": "",
  "industries": [62020, 70229, 47990],
  "location": "Leeds",
  "locationMaxDistance": 30,
  "status": "Active",
  "incorporationDateFrom": "01/01/2018",
  "incorporationDateTo": "31/12/2024",
  "directorAgeMin": 40,
  "directorAgeMax": 50,
  "directorAgeFilterType": "any",
  "maxOtherCompaniesAtAddress": 50,
  "financialFilters": [
    {
      "filterName": "turnoverrevenue",
      "description": "Turnover / Revenue",
      "minValue": 5000000,
      "maxValue": 500000000,
      "category": "Profit and Loss",
      "isDurationBased": true,
      "durationType": "Duration"
    }
  ],
  "sendAlerts": false,
  "queryName": "",
  "sortOrder": "",
  "pageNumber": 1,
  "pageSize": 10,
  "id": 0
}

{
  "apiVersion": "2",
  "industries": [62020],
  "financialFilters": [
    {
      "filterName": "TurnoverRevenue",
      "description": "TurnoverRevenue",
      "minValue": 5000000,
      "maxValue": 500000000
    }
  ]
}

{
  "success": true,
  "count": 10535,
  "error": null,
  "errorMessage": null
}

{
  "status": "Ok",
  "errorMessage": null,
  "lastDataUpdatedDate": "20/02/2026",
  "totalResults": 10535,
  "pageNumber": 1,
  "pageSize": 100,
  "totalPages": 106,
  "hasNextPage": true,
  "hasPreviousPage": false,
  "results": [
    {
      "companyNumber": "12345678",
      "title": "EXAMPLE CONSULTING LTD",
      "companyStatus": "Active",
      "companyIncorporated": "12/05/2019",
      "companyRegisteredAddress": "LEEDS",
      "regAddressLine1": "1 EXAMPLE STREET",
      "regAddressPostTown": "LEEDS",
      "regAddressPostCode": "LS1 1AA",
      "regAddressCountry": "UNITED KINGDOM",
      "sicCode1": "62020",
      "sicCode1Text": "Information technology consultancy activities",
      "accountsDueDate": "30/09/2026",
      "accountsOverDue": false,
      "cs01DueDate": "18/06/2026",
      "cs01OverDue": false,
      "resultNumber": 1,
      "companyData": {
        "status": "Ok",
        "profile": {
          "companyNumber": "12345678",
          "companyName": "Example Consulting Ltd"
        },
        "financials": {
          "company_financial_list": []
        },
        "officers": [],
        "psc": [],
        "error_message": null
      }
    }
  ]
}

companyData follows the same contract as /api/companydata: status, profile, financials, officers, psc, error_message. See /Documentation/v2/CompanyData for full nested field details.

Root-level financial snapshot fields are not included in results[]. Use companyData.financials.company_financial_list for financial-year details.

Test key behavior: when test credentials are used, companyData.financials.company_financial_list is reduced to sample-year data, root-level SIC fields (sicCode1-4, sicCode1Text-4Text) are masked, and sensitive profile/officers/psc fields are redacted as "Not available when using Test key".

When financialFilters are invalid, the API returns a helpful 400 payload with per-filter details and suggested closest matches.

{
  "success": false,
  "count": 0,
  "error": "InvalidRequest",
  "errorMessage": "One or more request fields are invalid.",
  "validationErrors": [
    {
      "field": "locationMaxDistance",
      "message": "locationMaxDistance must be between 0 and 30."
    }
  ]
}

{
  "success": false,
  "count": 0,
  "error": "InvalidFinancialFilters",
  "errorMessage": "One or more financial filters are invalid.",
  "validationErrors": [
    {
      "index": 0,
      "message": "Unknown filterName. Provide a valid filterName from the documentation.",
      "providedDescription": null,
      "providedFilterName": "TurnoverRevenuee",
      "suggestions": ["TurnoverRevenue", "NetAssetsLiabilities", "CashBankOnHand"]
    }
  ]
}

• apiVersion: required and must be "2".
• At least one search criterion/filter must be provided (for example searchTerm, industries, location, date range, director age, status, or financialFilters).
• searchTerm: minimum 3 characters (when provided) and only allowed characters used by portal validation.
• locationMaxDistance: must be between 0 and 30.
• directorAgeMin: must be at least 18 (if provided).
• directorAgeMax: must be 98 or less (if provided).
• Date ranges: invalid dates are rejected; for each pair, from cannot be later than to.
• financialFilters: unknown filters and minValue > maxValue are rejected.