/api/findcompanies/metadata

Version and Endpoint

Request

Use this endpoint to get the count of companies matching your filter criteria before making a request to the main findcompanies endpoint.

Method Type

Authentication

HTTP Response Codes

Request Body

Same payload model as POST /api/findcompanies (FindCompaniesCriteria).

SIC lookup for the industries field: /Documentation/v2/SicCodes.

Request JSON Example

{
  "apiVersion": "2",
  "industries": [62020, 70229],
  "location": "Leeds",
  "locationMaxDistance": 30,
  "status": "Active",
  "directorAgeMin": 40,
  "directorAgeMax": 50,
  "directorAgeFilterType": "any",
  "financialFilters": [
    {
      "filterName": "TurnoverRevenue",
      "description": "TurnoverRevenue",
      "minValue": 5000000,
      "maxValue": 500000000
    }
  ]
}

Response Example

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

If invalid financial filters are provided, this endpoint returns 400 with details and closest-match suggestions.

Error Response Example

{
  "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"]
    }
  ]
}

{
  "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."
    }
  ]
}

Validation Rules

• 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.

Response

Filter Definitions

The current filter definitions (labels/categories/filter keys) are listed below.

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

All Searchable Financial Filters

The filter keys shown below already remove the taxonomy prefixes (e.g. core_, direp_, aurep_). Use the values listed here when supplying financialFilters[].filterName in search or metadata requests.

The full list below represents the filters currently searchable via financialFilters payloads.