Filtering

Using filtering parameters

The most common starting point with Vainu API is to find the correct company or companies with the data or data ranges you have in mind.

With the filtering parameters, you can build complex searches or simple targeting queries to get correct results. Filtering parameters are available for either when searching for companies or signals from our databases. The most simple query might be defining a business ID to find the correct entity, while more complex queries might include combinations of financial, technographic, or location parameters.

Filter types

Each filtering parameter can be used as they are to get all results where this value is exactly as requested. Sometimes this isn't enough and parameters can be combined with specific suffixes to get more flexible results or to do a certain type of operation.

Each filter type is added to the end of the parameter name.

Supported filter types are:

Filter type

Explanation

Example

__gte

Value has to be greater or equal

staff_number__gte

__gt

Value has to be greater

staff_number__gt

__lte

Value has to be less or equal

turn_over__lte

__lt

Value has to be less

turn_over__lt

__startswith

String starts with the value

company_name__startswith

__contains

String includes this value (case sensitive)

company_name__contains

__icontains

String includes this value (case insensitive)

company_name__icontains

__ne

Value is not equal to his. Use "null" to filter out non existing values.

phone__ne

📘

Case insensitive parameters

Parameters: company_name, visiting_city, city, visiting_municipality, municipality are case insensitive by default.

Combination of multiple parameters

Multiple filtering parameters can be used to build more complex queries. If the same parameter is used multiple times they are processed as an AND query. If different parameters are used multiple times they are processed as an OR query. Both same and different parameters can be used in the same query.

Format of the business ID

The behavior of the business_id parameter differs slightly depending on whether or not the country parameter is used.

If one country is given, the business_id does not have to be in exactly the same format as in the Vainu database. Querying with ?country=NL&business_id=2123341 would find a company with business_id of NL2123341.

If none or more than one country is given, the business ID should be in the same format as in the Vainu database, or it should be in a format that is unique to a country. A business id that is unique to a country should have the country code as a prefix (FI2123341, NL2123341) or have a format such as 0123456-7 which is unique to Finnish business ids.

Multiple business IDs

Sometimes you have multiple business IDs and wish to get data from these. In this case, you can use the business_id parameter with multiple values when they are separated with a comma, all the values as processed as an OR.

https://api.vainu.io/api/v2/companies/?business_id==DK39248530,DK40494197

Using queries built inside the Vainu platform

The Vainu platform offers a search engine where multiple complex queries can be constructed in a visual interface. These lists are considered to be either dynamic or static. Dynamic lists are based on filters and content in the list changes when the data changes. Static lists are user uploaded or inserted companies where the content of the list stays the same.

Vainu API offers tools to manage these lists, which are discussed in greater detail under Lists and Customer data. For filtering purposes, these lists can be used as filtering parameters and the content created at the platform can be accessed through the API.

List parameter accepts only the list ID found either from the Lists API or from the URL at the platform.

https://api.vainu.io/api/v2/companies/?list=5ca6d481f447382da73a8ef4

Inactive companies

Vainu offers two different fields to imply the status of the company. These fields are status and nstatus. Status is the official, usually country-specific status from the local official authorities. Vainu has created a normalized status (nstatus) where the value is either active or inactive.

Matching

Vainu API offers a built-in matching function. Matching is enabled by giving matching=true as a parameter. When using the matching functionality API will return a single company if an accurate match is found. When no match or accurate match can't be found with the data sent, no companies will be returned.

All the parameters support incomplete and even slightly wrong data when using matching functionality and there is no need to use types of filtering parameters. The country parameter is usually recommended to be used, as it will greatly increase matching accuracy.

📘

Fields supporting matching

country, company_name, business_id, address, domain

Supported fields for filtering

Parameter name

Type

Description

address

string

Postal street address

address_s

string

area

alexa_rank_global

integer

Global alexa rank

basic_modified

datetime

Timestamp when basic data has been updated

business_id

string

Business id / organisation number of the company

city

string

City of postal address

company_keywords

string

company_name

string

Company name

company_name_l

string

Company name array, split by whitespace. Efficient for __startswith searches.

contacts__phone

string

Phone numbers of contacts

country

string

Country of the company

development_of_turnover

float

Turnover change in percentage

digitality

float

Vainu index describing digital adoption in the company (from 0 to 1)

domain

string

Company main domain

employer_register_date

datetime

Datetime when company has been registered to employer register

facebook_link

string

Link to the facebook profile

facts_numeric

financial_statement_keywords

string

Written content of financial statements

form_of_company

string

Form of company

industry_codes

leads

leads.content

link

string

Link to main website of company

linkedin_id

string

LinkedIn Id of the company

marketility

float

Vainu index describing marketing tech used by company (from 0 to 1)

mother

string

Business id of the mother company in the group

mother_foreign

string

Business id of the mother company of the group, if the company is from another country

municipality

string

Municipality of the postal address

modifications

datetime

Timestamp when the company data has been updated

nstatus

string

Normalised status of the company (inactive or active)

phone

string

Main phone number of the company

postal

string

Postal number of the postal address

profit

float

Profit of the company in percentage

prospect_addresses

prospect_addresses__address

string

Street addresses of company locations

prospect_addresses__city

string

Cities of company locations

prospect_addresses__municipality

string

Municipalities of company locations

prospect_addresses__office_name

string

Office names of company locations

prospect_addresses__postal

string

Postal numbers of company locations

prospect_addresses__region

string

Regions of company locations

prospect_addresses__types

string

prospect_addresses__industry_codes

Industry code of company locations

prospectexport_target

region

string

Region of the postal address

registration_date

datetime

Main registrations date for the company

related_links

string

related_links__link

string

sociality

float

Vainu index for social media usage (from 0 to 1)

staff_number

integer

Staff number

staff_number_growth

float

Percentage of change of staff number

status

string

Official status of the company

turn_over

float

Revenue of the company (EUR)

turn_over_local

float

Revenue in local currency

twitter_link

string

Link to twitter profile of the company

urls_keywords

string

Keywords collected from company website

urls_web_tags__name

string

Technologies collected from company website

urls

string

Other URL's belonging to company

vid

string

Vainu ID for the company

vainu_custom_industry

string

Vainu custom industry name

visiting_address

string

Visiting street address

visiting_address_s

string

visiting_city

string

City of visiting address

visiting_municipality

string

Municipality of visiting address

visiting_postal

string

Postal number of the visiting address

visiting_region

string

Region of the visiting address

Filtering examples

We have collected some examples of filtering parameters on the tabs below.

# Single business id with country prefix
https://api.vainu.io/api/v2/companies/?business_id=NO918443525

# Single business id without country prefix
https://api.vainu.io/api/v2/companies/?country=NO&business_id=918443525

# Multiple business id's
https://api.vainu.io/api/v2/companies/?business_id==DK39248530,DK40494197
# Company with a name Vainu Finland Oy
https://api.vainu.io/api/v2/companies/?company_name=Vainu%20Finland%20Oy&country=FI

# Any word of company name begins with Vainu
https://api.vainu.io/api/v2/companies/?company_name_l__startswith=vainu&country=FI
# Domain vainu.com
https://api.vainu.io/api/v2/companies/?country=FI&domain=vainu.com

# Domain starts with vainu
https://api.vainu.io/api/v2/companies/?country=FI&domain__startswith=vainu
# Country and region
https://api.vainu.io/api/v2/companies/?country=FI&ampregion__exact=FI-18

# Postal code starts with
https://api.vainu.io/api/v2/companies/?visiting_postal__startswith=905&country=FI

# Postal code range
https://api.vainu.io/api/v2/companies/?visiting_postal=50000-51019&limit=20&country=SE
# Vainu custom industry starts with "construction"
https://api.vainu.io/api/v2/companies/?country=FI&vainu_custom_industry__startswith=construction

# Companies with Finnish industry code starting with 60
https://api.vainu.io/api/v2/companies/?country=FI&industry_codes__startswith=60

# 20 companies with the biggest turn over with Finnish industry code 60201
https://api.vainu.io/api/v2/companies/?country=FI&industry_codes__startswith=60201&limit=20&order=-turn_over
# Companies with Zendesk as recongized technology
https://api.vainu.io/api/v2/companies/?country=FI&urls__web_tags__name__startswith=zendesk
# URL Keywords
https://api.vainu.io/api/v2/companies/?country=NL&urls_keywords__startswith=machine%20learning

# Company keywords
https://api.vainu.io/api/v2/companies/?country=FI&company_keywords__startswith=database

# Financial statement keywords
https://api.vainu.io/api/v2/companies/?country=FI&financial_statement_keywords__startswith=growth
# Staff number over 100
https://api.vainu.io/api/v2/companies/?staff_number__gt=100

# Turn over between 500000 - 600000
https://api.vainu.io/api/v2/companies/?turn_over__gte=500000&turn_over__lte=600000