Advanced Search

Overview

The advanced search endpoint (/search/advanced) provides filtering and field projection capabilities for sophisticated company queries. This allows you to create precise searches that return exactly the data you need.

Filter Operations

The advanced search supports a comprehensive set of filter operations:

Comparison Operators

Operator	Description	Example
=	Equal to	sector = "private_sector"
!=	Not equal to	sector != "public_sector"
>=	Greater than or equal to	establishmentDate >= "2020-01-01"
>	Greater than	establishmentDate > "2020-01-01"
<=	Less than or equal to	establishmentDate <= "2023-12-31"
<	Less than	establishmentDate < "2023-12-31"

Text Operations

Operator	Description	Example
CONTAINS	Text contains substring	businessName CONTAINS "Kontakto"
NOT CONTAINS	Text does not contain substring	businessName NOT CONTAINS "Test"
STARTS WITH	Text starts with substring	businessName STARTS WITH "Oy"
NOT STARTS WITH	Text does not start with substring	businessName NOT STARTS WITH "Test"

List Operations

Operator	Description	Example
IN	Value is in list	sector IN ["private_sector", "limited_liability_business"]
NOT IN	Value is not in list	sector NOT IN ["public_sector", "other"]

Range Operations

Operator	Description	Example
TO	Range between values	establishmentDate TO "2020-01-01" "2023-12-31"

Existence Checks

Operator	Description	Example
EXISTS	Field exists and has value	vatId EXISTS
NOT EXISTS	Field does not exist or is null	vatId NOT EXISTS
IS NULL	Field is explicitly null	vatId IS NULL
IS NOT NULL	Field is not null	vatId IS NOT NULL
IS EMPTY	Field is empty string or empty array	auxiliaryNames IS EMPTY
IS NOT EMPTY	Field is not empty	auxiliaryNames IS NOT EMPTY

Logical Operators

Combine multiple filters using logical operators:

• AND: All conditions must be true
• OR: At least one condition must be true

Examples

# Active companies in Helsinki with green rating
operationalStatus = true AND domicileCity = "Helsinki" AND kontaktoRating.color = "green"

# Companies in specific sectors or cities
sector IN ["private_sector", "limited_liability_business"] OR domicileCity IN ["Helsinki", "Espoo"]

# Complex combination
operationalStatus = true AND (sector = "private_sector" OR sector = "limited_liability_business") AND establishmentDate >= "2020-01-01"

Field Projection

Control exactly which fields are returned using the fields parameter. This significantly improves performance by reducing response size.

Available Fields

Basic Company Information

• businessId - Finnish business ID (Y-tunnus)
• businessName - Primary business name
• vatId - VAT identification number
• auxiliaryNames - Alternative business names
• parallelNames - Parallel business names

Status and Classification

• operationalStatus - Whether company is active
• statusAsOf - Status timestamp
• statusDescription - Status description
• countryCode - Country code
• languageCode - Language code
• sector - Kontakto sector classification

Location and Industry

• domicileCity - Company's city
• domicileCode - City code
• industryDescription - Industry description
• tol2008Code - TOL industry classification code

Legal Information

• legalForm - Legal form description
• legalFormCode - Legal form code
• establishmentDate - Company establishment date
• createdAt - Record creation timestamp

Nested Fields

• kontaktoRating.color - Rating color (green/yellow/red)
• kontaktoRating.reason - Rating reason
• kontaktoRating.asOf - Rating timestamp

Array Fields

• address.city - Address city
• address.street - Address street
• website.name - Website name
• website.url - Website URL
• domain.name - Domain name
• phoneNumber.number - Phone number