Matchplat API Docs

POST /explore/simple-semantic

Search for companies using keywords and structured filters. Allows to specify keyword (OR), must (AND), and mustNot (NOT) arrays for semantic search, in addition to standard filters. The response is paginated and includes the searchContextId and input parameters.

Request Body

Field Type Description
filters ExploreFilters Filters object for company search (see details below). See ExploreFilters object details below.
semantic SemanticSearchInput Object for semantic search (see details below). See SemanticSearchInput object details below.
page Int Page number (optional, default 1)

ExploreFilters

Field Type Description
countriesIso2 String[] ISO2 codes of the countries (required). Available values are those supported by the API. Countries limit is 1 for Lite and Plus, 5 for Simple Semantic.
regions String[] List of regions to include in the filter. Available values are provided by a dedicated endpoint given the country.. See here
cities String[] List of cities to include in the filter. Available values are provided by a dedicated endpoint given the country.. See here
postcode String[] List of postal codes to include in the filter
dateOfIncorporationGte DateTime Company incorporation date (greater than or equal to)
dateOfIncorporationLte DateTime Company incorporation date (less than or equal to)
operatingRevenueGte Int Minimum operating revenue (in local currency)
operatingRevenueLte Int Maximum operating revenue (in local currency)
numberOfEmployeesLte Int Maximum number of employees
numberOfEmployeesGte Int Minimum number of employees
standardisedLegalForm String[] List of standardized legal forms
nationalSectors String[] National sector codes. Available values are provided by a dedicated endpoint given the country.. See here
naceCodes String[] NACE codes to include in the filter. Available values are provided by a dedicated endpoint.. See here
naicsCodes String[] NAICS codes to include in the filter. Available values are provided by a dedicated endpoint.. See here
sicCodes String[] SIC codes to include in the filter. Available values are provided by a dedicated endpoint.. See here
isPrimaryCodes Boolean Filter on primary codes (true/false)
isSecondaryCodes Boolean Filter on secondary codes (true/false)
categories String[] Custom categories to include in the filter. Values correspond to categoryOfTheCompany in the company object.. See Company Object (categoryOfTheCompany)
status String[] Company status values to include. Values correspond to status in the company object.. See Company Object (status)
listedDelistedUnlisted String[] Listing status (listed, delisted, unlisted)

SemanticSearchInput

Field Type Description
keywords String[] Keywords (OR logic) at least 1 required
must String[] Words that must be present (AND logic)
mustNot String[] Words that must not be present (NOT logic)

Response 200

Field Type Description
companies Company[] Array of found companies (max 25 per page)
totalCompanies Int Total number of found companies
totalPages Int Total number of pages
page Int Current page number
pageSize Int Page size (fixed 25)
searchContextId String Search context identifier
input Object Input parameters received

Company

See the Company Object section for detailed field descriptions.

Example

{
  "companies": [],
  "totalCompanies": 0,
  "totalPages": 1,
  "page": 1,
  "pageSize": 25,
  "searchContextId": "b7e6a2c1-4f3d-4e2a-9c1a-2b3e4d5f6a7b",
  "input": {
    "filters": { "country": "IT" },
    "semantic": { "keyword": ["AI", "machine learning"], "must": ["software"], "mustNot": ["agricoltura"] },
    "page": 1
  }
}

Example curl call

curl -X POST "/explore/simple-semantic" \
  -H "x-api-key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "countriesIso2": ["IT"],
    },
    "semantic": {
      "keywords": ["AI", "machine learning"],
      "must": ["software"],
      "mustNot": ["agricoltura"]
    },
    "page": 1
  }'

Other codes