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.
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:
Value has to be greater or equal
Value has to be greater
Value has to be less or equal
Value has to be less
String starts with the value
String includes this value (case sensitive)
String includes this value (case insensitive)
Value is not equal to his. Use "null" to filter out non existing values.
Case insensitive parameters
Parameters: company_name, visiting_city, city, visiting_municipality, municipality are case insensitive by default.
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.
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.
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.
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.
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.
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
Postal street address
Global alexa rank
Timestamp when basic data has been updated
Business id / organisation number of the company
City of postal address
Company name array, split by whitespace. Efficient for __startswith searches.
Phone numbers of contacts
Country of the company
Turnover change in percentage
Vainu index describing digital adoption in the company (from 0 to 1)
Company main domain
Datetime when company has been registered to employer register
Link to the facebook profile
Written content of financial statements
Form of company
Link to main website of company
LinkedIn Id of the company
Vainu index describing marketing tech used by company (from 0 to 1)
Business id of the mother company in the group
Business id of the mother company of the group, if the company is from another country
Municipality of the postal address
Timestamp when the company data has been updated
Normalised status of the company (inactive or active)
Main phone number of the company
Postal number of the postal address
Profit of the company in percentage
Street addresses of company locations
Cities of company locations
Municipalities of company locations
Office names of company locations
Postal numbers of company locations
Regions of company locations
Industry code of company locations
Region of the postal address
Main registrations date for the company
Vainu index for social media usage (from 0 to 1)
Percentage of change of staff number
Official status of the company
Revenue of the company (EUR)
Revenue in local currency
Link to twitter profile of the company
Keywords collected from company website
Technologies collected from company website
Other URL's belonging to company
Vainu ID for the company
Vainu custom industry name
Visiting street address
City of visiting address
Municipality of visiting address
Postal number of the visiting address
Region of the visiting address
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&region__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
Updated 9 months ago