NAV Navigation
Python Shell NodeJS

Vainu API v2

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Integration partnership

If you happen to be a software provider yourself and you're interested in providing your customers with new kind of value, you may want to read more about our integration partnersip.

URLs

The base URL for the Vainu apis is https://api.vainu.io/api/v2/

Datetime format

All datetime values are in ISO8601 format.

Status codes

List of status and error codes and their definitions.

Authentication

All parts of our API require authentication. We offer traditional HTTP basic access authentication and API key authentication.

Additionally, API Permissions must be enabled on the user account that is used to authenticate API requests.

Successful authentication allows access to corresponding resources as the used user credentials include.

Basic Access authentication

Basic access authentication – commonly referred to as "basic auth" or HTTP authentication – uses the same login credentials as the web interface.

Simply add Authorization header to your request with a base64 encoded username and password. Example header: Authorization: Basic .

API Key authentication

API-Key: c031d56b97320ab3c0690850d52d8059d998f4d7851b3c15e2586b5594745aee

API keys are obtained through the web interface. In order to generate an API key in the first place, user must have API permissions enabled. Currently three simultaneously active keys per user are allowed.

To generate new API keys and list existing ones, go to Settings and open API Keys -tab. This page lists all active API keys generated by the user and allows fetching their corresponding API tokens.

Deleting keys (and thus preventing their further use) is also possible through this page. API keys also track some information about their use that is displayed on this page.

Companies and signals

Filtering

Using filters allows you to get only certain companies or signals.

The same filters can be used to filter both resources. When using a company filter to filter signals, only signals for matching companies will be returned, and likewise, when using signal filters to filter companies, only companies with matching signals will be returned.

The company endpoint also allows you to find the best company to match your data. (See companies.)

For best performance include the country filter in your filter query.

Supported filter types:

No filter type is an exact match

Note that the following fields are always case insensitive: company_name, visiting_city, city, visiting_municipality, municipality

OR and AND:

Get companies that have a turn over of at least 100000 AND are located in Finland AND are located in Helsinki:

https://api.vainu.io/api/v2/companies/?turn_over__gte=100000&city=Helsinki&country=FI

When using different filter parameters, they are treated as AND.



Get companies that have a turn over of at least 100000 AND are located in Finland AND are located in Helsinki OR Tampere:

https://api.vainu.io/api/v2/companies/?turn_over__gte=100000&city=Helsinki&city=Tampere&country=FI

When using the same filter parameter repeatedly, they are treated as OR.



Supported fields for filtering:

address, address_s, alexa_rank_global, area, basic_modified, business_id, city, company_keywords, company_name, company_name_l, contacts__phone, country, development_of_turnover, digitality, domain, employer_register_date, facebook_link, facts_numeric, financial_statement_keywords, form_of_company, industry_codes, leads, leads.content, link, linkedin_id, marketility, mother, mother_foreign, municipality, modifications, nstatus, phone, postal, profit, prospect_addresses, prospect_addresses__address, prospect_addresses__city, prospect_addresses__municipality, prospect_addresses__office_name, prospect_addresses__postal, prospect_addresses__region, prospect_addresses__types, prospect_addresses__industry_codes, prospectexport_target, region, registration_date, related_links, related_links__link, sociality, staff_number, staff_number_growth, status, turn_over, turn_over_local, twitter_link, urls_keywords, urls, vid, vainu_custom_industry, visiting_address, visiting_address_s, visiting_city, visiting_municipality, visiting_postal, visiting_region



Multiple business_id's treated as an OR

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

Filtering by business_id

The behaviour 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 countries are given, the business id should be in the same format as in 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_id's can be queried simultaneously by separating business_id values with a comma (?business_id==DK39248530,DK40494197)

List as a filter

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

Using lists from Vainu UI as filters:

To get the id of a list, use the lists api

OR

go to the list in Vainu UI and from the url, copy the id after "prospects/": https://app.vainu.io/vainu/prospects/5ca6d481f447382da73a8ef4/?q=eyJxdWVyeSI6InFpZD...

Region filtering

https://api.vainu.io/api/v2/companies/?country=FI&region__exact=FI-18&count=include

Region filtering

FIlter regions with ISO 3166-2 standard. Example ISO 3166-2 areas for Nordics:

Range query with postal code:

https://api.vainu.io/api/v2/companies/?visiting_postal=50000-51019&limit=20&country=SE

Postal code is exactly 90500:

https://api.vainu.io/api/v2/companies/?visiting_postal__exact=90500&country=FI

Postal code startswith 905:

https://api.vainu.io/api/v2/companies/?visiting_postal__startswith=905&country=FI

Address and postal code queries

For best results when filtering with addresses, we recommend filtering companies by using the visiting_ fields ( visiting_address, visiting_city, visiting_postal). If our data has no visiting address but we have a regular address, the regular address is copied to visting address data. In the case of Finnish real estate companies, the visiting_ fields are replaced with the location of the building, if the data is available.






Filter Swedish companies with postal code range 50000-51019 that are active:

https://api.vainu.io/api/v2/companies/?visiting_postal=50000-51019&limit=20&country=SE&nstatus=active

Filter Swedish companies with postal code range 50000-51019 that are inactive:

https://api.vainu.io/api/v2/companies/?visiting_postal=50000-51019&limit=20&country=SE&nstatus=inactive

Company status queries

Filtering out inactive companies can be done by using the nstatus (Normalized status) filtering parameter.

Definitions:

Get 20 companies with the biggest turn over with finnish industry code 60xxx.

https://api.vainu.io/api/v2/companies/?country=FI&industry_codes__startswith=60&limit=20&order=-turn_over

Get 20 companies with the biggest turn over with finnish industry 60201 (Television programming and broadcasting activities (excl. pay television channels)

https://api.vainu.io/api/v2/companies/?country=FI&industry_codes__startswith=60201&limit=20&order=-turn_over

Industry codes queries

Use industry_codes field to filter with industry_code. Field uses the local value of the industry code spesific to the country. The first value of the list represents the primary industry code.

Local formats for countries:

Vainu custom industry

Vainu categorizes companies to different industries based on the written content on their website. Companies can be filtered with different Vainu custom industries (vainu_custom_industry).

Filter by technologies

https://api.vainu.io/api/v2/companies/?country=FI&vainu_custom_industry__startswith=construction

Technology queries

Vainu collects data from various technologies used by the company. Companies can be filtered based on technology name using web tags (urls_web_tags_name).

Filter by technologies

https://api.vainu.io/api/v2/companies/?country=FI&urls__web_tags__name__startswith=zendesk

Keyword queries

Vainu collects text data from different sources which can be used to filter companies. URL keywords (urls_keywords) are collected from company website, company keywords (company_keywords) are collected from company descriptions and financial statement (financial_statement_keywords) keywords from financial statements filed by the company.

Filter by URL keywords

https://api.vainu.io/api/v2/companies/?country=NL&urls_keywords__startswith=machine%20learning

Filter by company keywords

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

Filter by financial statement keywords

https://api.vainu.io/api/v2/companies/?country=FI&financial_statement_keywords__startswith=growth



More examples:

Filter with business IDs: 0970409-8,0357502-9,2127346-2:

https://api.vainu.io/api/v2/companies/?business_id=09704098&business_id=03575029&business_id=21273462

Companies with “Vainu” in their company_name:

https://api.vainu.io/api/v2/companies/?company_name\__icontains=Vainu&country=FI&limit=20

Companies with exact company name “Nokia Oyj”:

https://api.vainu.io/api/v2/companies/?company_name=Nokia Oyj&country=FI

Companies with turnover between 500000-510000 :

https://api.vainu.io/api/v2/companies/?turn_over\__gte=50000&turn_over\__lte=51000

Modification queries

Changes in the company data can be queried either with Basic modified (basic_modified) or by adding modifications__ prefix to the preferred field name. Both parameters accept timestamps. Basic modified returns all companies where basic data (see list of fields available for modifications__ queries) has been modified on a given date or date range. Modifications__ prefix returns all companies where the corresponding data field has been modified on a given date or date range.

Supported fields for modifications__ queries are: company_name, company_names, domain, industry_codes_local, nstatus, phone, profit, restricted_for_marketing, staff_number, status, turn_over, vainu_status, visiting_address, visiting_city, visiting_county, visiting_municipality and visiting_postal.

Companies with turnover between 500000-510000 AND basic information has been updated since 20.4.2016 16:00:

https://api.vainu.io/api/v2/companies/?basic_modified\__gt=2016-04-20T16:00:00&&turn_over\__gte=50000&turn_over\__lte=51000

Get all companies in Sweden where address data has changed since 2021-06-15T07:00:

https://api.vainu.io/api/v2/companies/?modifications__prospect_addresses__gte=2021-06-15T07:00:00&country=SE

Get Companies

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Accept': 'application/json',
  'API-Key': API_KEY
} 

r = requests.get('https://api.vainu.io/api/v2/companies/',
	params={},
	headers=headers
)

print(r.json())


curl -X GET https://api.vainu.io/api/v2/companies/ \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).

const headers = {
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/companies/',
{
  method: 'GET',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /companies/

Companies endpoint supports Get and Post requests.

Filtering

See filtering.

Finding the best company match

If you want to find a specific company that you already have some data on (for example, the name of the company, a business id, address, website, etc.) you can use all of this data to find the best match. This method of finding a company can be used with incomplete or even slightly wrong data, and still allow you to find the correct company. To enable matching instead of filtering, use matching=true. With matching enabled, you can use the following parameters to find the best matching company:

The country parameter will filter out companies in other countries, and it should be used for accurate matching.

Sorting

Sorting is specified with the ‘order’ parameter. Sorting is possible with all the fields that support for filtering. Ascending order can be specified with a leading ‘-‘ character.

Fast sorting (ascending or descending) is supported with fields: business_id, company_name, visiting_postal, visiting_city , business_id, vainu_score, turn_over, alexa_rank_global.

Count

You can get the total number of results without paginating through them all.

Get only the total number of results with parameter count=true or include the count in the results with count=include. Including the count in the results will cause the query to be 1.5-2 times slower.

Industry code 87301 with 30 results from the 20th result onward:

https://api.vainu.io/api/v2/companies/?industry_codes=87301&limit=30&offset=20&country=FI

Pagination

To paginate through results, use the limit and offset parameters.

Use limit to set the maximum number of results per response. The default limit is 20 and the maximum limit is 1000.

offset sets the starting point of the results

Fields to return

Get the fields company_name, business_id and turn_over:

https://api.vainu.io/api/v2/companies/?visiting_postal\__startswith=905&country=FI&fields=company_name&fields=business_id&fields=turn_over

You can select which fields to return using the fields parameter. Only returning the necessary fields can have a large impact on performance.

Get all available fields:

https://api.vainu.io/api/v2/companies/?visiting_postal\__startswith=905&country=FI&fields=all

By default not all fields are returned. To get all fields, use the argument all






About addresses data

The company data includes two types of address data (fields such as postal, city, address): fields starting with visiting_, and fields not starting with visiting_.

visiting_: The address of the headquarters.

without visiting_: The postal address.

If no data is found for the visiting_ fields, the data is replaced with data from the fields without visiting_.

In the case of Finnish real estate companies, the visiting_ fields are replaced with the location of the building, if the data is available.

All addresses can be found in the addresses field, which contains all available addresses in an array. Real estate, visiting and postal addresses can be distinguished with the field types. Addresses may have multiple types.

About group data

The group data includes the data of the group where queried company belongs with the data of highest entity in the group structure.

Example responses

200 Response

{
  "results": [
    {
      "linkedin_id": "3803996",
      "visiting_municipality": "HELSINKI",
      "development_of_turnover": "-4.30",
      "industry_codes": [
        "62010",
        "J"
      ],
      "visiting_city": "HELSINKI",
      "description": "Vainu is a company data platform helping you focus your sales and marketing efforts on the companies most likely to convert, buy more, or churn. With Vainu you find actionable account insights, identify timely leads, and determine the most valuable sales prospects to your business.\n\nCurrently, over 2,000 organizations and more than 14,000 individual business professionals save time and sell more with a better hit rate - thanks to Vainu.\n\nOur mission is to collect, read and understand all the information ever written about every company in the world, and then make this information comprehensible to everyone.\n\nThanks to enormous amounts of data collected from open and public sources as well as created by our own machine learning algorithms, Vainu has the most extensive, precise, and up-to-date information on which companies you should allocate your sales and marketing efforts to.\n\nVainu has offices in Helsinki, Tampere, New York, Amsterdam, Rotterdam, Oslo, Stockholm and Copenhagen. We've grown from 3 employees to over 180 in four years and are constantly looking for more talented and passionate individuals to join our adventure.",
      "vainu_link": "https://app.vainu.io/vainu/prospect/708216/",
      "city": "HELSINKI",
      "staff_number_is_estimate": false,
      "profit": "-15.20",
      "industry_code": "62010",
      "basic_modified": "2019-05-20T14:06:14.245000",
      "turn_over_is_estimate": false,
      "company_name": "Vainu. io Software Oy",
      "visiting_postal": "00130",
      "staff_number": 39,
      "sociality": 0.6,
      "status": "active",
      "turn_over_local": "895766",
      "turn_over": "895766",
      "municipality": "HELSINKI",
      "registration_date": "2013-08-07",
      "business_id": "25578642",
      "phone": null,
      "link": "https://product.vainu.io",
      "address": "Eteläesplanadi 12",
      "visiting_address": "Pohjoinen Makasiinikatu 3",
      "marketility": 0.8,
      "postal": "00130",
      "alexa_rank_global": null,
      "twitter_link": "https://twitter.com/vainuio?ref_src=twsrc%5Egoogle%7Ctwcamp%5Eserp%7Ctwgr%5Eauthor",
      "country": "FI",
      "facebook_link": "https://www.facebook.com/vainuio/?hc_ref=SEARCH&fref=nf",
      "mother": null,
      "industry_code_2": 62,
      "mother_foreign": null,
      "industry_code_5": 62010,
      "currency_code": "EUR"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» results [object] false none none
»» form_of_company string false none Company's official form of business (limited liability company, corporation etc.).
»» bs_total_current_liabilities float false none Sum of total current liabilities, as seen on the balance sheet.
»» linkedin_id string false none Company's Linkedin identifier in numeric format (e.g. linkedin.com/12345 = 12345).
»» jurisdiction string false none State under whose laws the company operates.
»» leads array false none News articles that are matched to the company.
»» registers array false none Public registers that the company is listed on (e.g. export registry)
»» form_of_registration string false none none
»» foundation_date date-time false none Date the company was founded.
»» company_hiring_links array false none Link to the company's career page (can be multiple).
»» kr_turnover_per_employee_local float false none Company's revenue divided by their employee count, as found on the balance sheet. In local currency.
»» xbrl_financial_statements array false none none
»» visiting_address_country string false none Country where the company's visiting address is located.
»» fax string false none Fax number of the company.
»» industry_estimated_date date-time false none Date the industry was estimated using Vainu's industry estimator.
»» total_funding_usd float false none Total sum of funding the company has received (USD).
»» business_id string false none Company's local business identification number (state registration number in the U.S.).
»» right_of_sign string false none Who has the right to sign for the company (e.g. board members), as found on the balance sheet.
»» visiting_postal_int integer false none Company's zip code for the visiting address.
»» alexa_rank_global integer false none Global Alexa rank for the company.
»» themes array false none Labels given by Vainu to characterize the company (actively hiring, cloud service enthusiast etc.)
»» alexa_country_code string false none Country that the company website is registered in for Alexa ranking.
»» countries array false none Countries the company has operations in.
»» website_page_count integer false none Total number of pages found on the company's website.
»» verified_by_users array false none none
»» industry_code_2 integer false none Two-digit version of the local industry classification code (e.g. NAICS, SIC).
»» industry_code_5 integer false none Five-digit version of the local industry classification code (e.g. NAICS, SIC).
»» kr_turnover_per_employee float false none Company's revenue divided by their employee count, as found on the balance sheet.
»» visiting_region string false none State the company's visiting address is located in.
»» visiting_country string false none Country the company's visiting address is located in.
»» facebook_posts_per_day float false none Average number of posts on the company's Facebook page per day.
»» lng float false none Longitude of the company's registered address.
»» salary_board float false none Compensation the board of the company receives, as seen in the financial statement.
»» bs_provisions_local float false none none
»» se_industry_code_5 integer false none 5-digit version of the Swedish industry classification code.
»» email string false none General email address for the company (e.g. info@vainu.io)
»» visiting_lng float false none Longitude of the company's visiting address.
»» accounting_firm string false none Auditor of the company, as seen in the financial statement.
»» avg_num_videos_per_month float false none Average number of videos posted per month on the company's Youtube channel.
»» bs_total_equity_and_liab float false none Total equity and liabilities, as seen on the balance sheet.
»» address string false none Company's registered address.
»» dividend float false none Paid dividends, as seen on the balance sheet.
»» stock_exchange_date date-time false none Date the company was listed on the stock exchange.
»» bs_total_current_liabilities_local float false none Total sum of current liabilities, as seen on the balance sheet.
»» company_name_s string false none none
»» country string false none Country the company's registered address is in.
»» region string false none State the company's registered address is in.
»» payroll_overhead_local float false none Total costs of payroll, as found in the balance sheet. In local currency.
»» products array false none none
»» visiting_lat float false none Latitude of the company's visiting address.
»» domains array false none Additional website URLs identified for the company.
»» financial_statements_consolidated array false none none
»» company_name_l array false none none
»» visiting_coordinates array false none Coordinates for the company's visiting address
»» industry_code_sbi string false none none
»» vid integer false none Company's unique Vainu identifier.
»» county string false none County the company's registered address is in.
»» employer_register_date date-time false none Date the company joined the employer registry (Europe only).
»» company_names array false none All variations of company names identified for the company.
»» staff_number_upperlimit integer false none Upper limit of the company's employee count range, when applicable.
»» vat_property_register_date date-time false none Date the company joined the local property registry (Europe only).
»» branch_number string false none Number of local branches identified for the company.
»» staff_number_estimate integer false none Estimated employee count for the company.
»» vat_register_date date-time false none Date the company joined the VAT registry (Europe only).
»» state_registration string false none none
»» restricted_for_marketing boolean false none none
»» bookkeeping_firm string false none Accounting firm for the company, as seen in the financial statement.
»» bs_total_turnover_assets float false none none
»» phone string false none Main phone number for the company.
»» bs_total_turnover_assets_local float false none none
»» modified date-time false none none
»» bs_total_long_term_debts float false none Sum of total long term debts, as seen on the balance sheet.
»» mother_foreign string false none Foreign parent company of the organization.
»» visiting_address string false none Visiting address of the company.
»» currency_code string false none Main currency used by the company as seen in the financial statement (USD, EUR).
»» cash_flow_from_op_percent float false none none
»» funding_rounds array false none Funding rounds raised by the company.
»» turnover_estimated_date date-time false none Date the revenue was estimated using Vainu's revenue estimator.
»» industry_codes_main_local array false none none
»» dissolution_registration_date date-time false none Date the company was dissolved.
»» bs_untaxed_reserves_local float false none none
»» career_page_job_count integer false none Numer of open jobs counted on the company's career page.
»» financial_statement_keywords array false none Full text from the financial statement.
»» isic_industry_code string false none Company's ISIC industry classification code.
»» visiting_address_s string false none none
»» visiting_county string false none County of the company's visiting address.
»» company_name string false none Official name of the company.
»» visiting_postal string false none Zip code of the company's visiting address.
»» status string false none Current registration status of the company (active, inactive etc.)
»» isic_industry_code_1 string false none One-letter category of the company's ISIC industry.
»» description string false none Text description of the company, extracted from public profiles.
»» dissolution_mode string false none none
»» bs_total_equity float false none Sum of total equity in the company, as seen in the balance sheet.
»» result_before_taxes float false none Company's earnings before interest and taxes (EBIT).
»» facebook_engagement_rate float false none Engagement rate of the company's Facebook page.
»» lat float false none Latitude of the company's registered address.
»» company_level integer false none none
»» charges array false none none
»» kr_net_margin_percent float false none Percentage of revenue remaining after all operating expenses, interest and tax.
»» staff_cls integer false none none
»» mother string false none Official company name of the parent company.
»» youtube_view_count integer false none Number of views on the company's Youtube page.
»» twitter_followers_count integer false none Number of Twitter followers.
»» bs_total_assets float false none Sum of total assets as found on the balance sheet.
»» development_of_turnover float false none Change in revenue from the previous year, as found on the balance sheet.
»» company_name_s_short string false none Shortened version of the company's name.
»» employee_salary_local float false none Total cost of employee salaries as found on the balance sheet.
»» industry_code_tol_2002 string false none Finnish industry classification code.
»» www_index_ip string false none Company's website IP address.
»» industry_codes_all array false none All identified industry codes for the company.
»» business_ids array false none All linked business ids of the company.
»» coordinates array false none Coordinates for the registered address of the company.
»» company_rss_links array false none Links to all identified rss feeds on the company's website.
»» form_of_company_vainu integer false none none
»» addresses [object] false none All identified addresses for the company.
»»» uid string false none Unique identifier for the location issued by Vainu
»»» business_id string false none none
»»» email string false none none
»»» phone string false none none
»»» staff_number integer false none none
»»» staff_number_upperlimit integer false none none
»»» staff_number_lowerlimit integer false none none
»»» address_details object false none none
»»»» po_box string false none none
»»»» instructions string false none none
»»»» street_number string false none none
»»»» care_of string false none none
»»»» floor string false none none
»»»» street_name string false none none
»»»» property_unit_number string false none none
»»»» entrance string false none none
»»» visiting_address_details object false none none
»»»» po_box string false none none
»»»» instructions string false none none
»»»» street_number string false none none
»»»» care_of string false none none
»»»» floor string false none none
»»»» street_name string false none none
»»»» property_unit_number string false none none
»»»» entrance string false none none
»»» country string false none none
»»» address_country string false none none
»»» visiting_address_country string false none none
»»» lat float false none Latitude
»»» visiting_lat float false none Latitude
»»» lng float false none Longitude
»»» visiting_lng float false none Longitude
»»» coordinates object false none none
»»»» type string false none Type of coordinates
»»»» coordinates [string] false none none
»»» city string false none none
»»» visiting_city string false none none
»»» office_name string false none none
»»» office_number string false none none
»»» office_type string false none none
»»» address string false none none
»»» visiting_address string false none none
»»» postal string false none none
»»» visiting_postal string false none none
»»» municipality string false none none
»»» visiting_municipality string false none none
»»» region string false none none
»»» types [string] false none none
»»» industry_codes_all [string] false none none
»»» industry_codes [string] false none none
»»» start_date string false none none
»»» modified date-time false none Timestamp when the location was last modified
»» address_details object false none none
»»» floor string false none none
»»» po_box string false none none
»»» entrance string false none none
»»» care_of string false none none
»»» property_unit_number string false none none
»»» street_number string false none none
»»» street_name string false none none
»»» instructions string false none none
»» vids array false none All linked unique identifiers for the company.
»» stock_symbol string false none Stock symbol (Ticker) for the company.
»» sociality float false none A score (between 0-1, 1 being maximum) that characterizes how advanced the company is with social media technologies.
»» youtube_subscriber_num integer false none Number of subscribers on the company's Youtube page.
»» municipality string false none County of the company's registered address.
»» registration_date date-time false none Date the business was registered with the local business authority (e.g. State).
»» marketility float false none A score (between 0-1, 1 being maximum) that characterizes how advanced the company is with marketing technologies.
»» postal string false none Zip code for the company's registered address.
»» bs_total_fix_assets float false none Sum of total fixed assets as found on the balance sheet.
»» bs_total_fix_assets_local float false none Sum of total fixed assets as found on the balance sheet. In local currency.
»» financial_statements array false none Full data from the financial statement per year.
»» num_subscribers_per_1000_views float false none Average number of subscribers per 1000 views on a company's Youtube page.
»» branch_status string false none none
»» domain string false none Website URL of the company.
»» visiting_city string false none City of the company's visiting address.
»» vainu_score float false none Score (0-100) describing completeness of the company profile in Vainu's database.
»» status_registration_date date-time false none none
»» rss_feeds object false none Links to RSS feeds found on the company website.
»» profit_estimate float false none Estimate of the generated profit for the year.
»» logo string false none Logo of the company.
»» bs_untaxed_reserves float false none Sum of the untaxed reserves of the company, as found in the balance sheet.
»» digitality float false none A score (between 0-1, 1 being maximum) that characterizes how digitally advanced the company is.
»» address_country string false none Country of where the registered address is located.
»» isic_industry_codes array false none All identified ISIC industry classification codes.
»» companynews_links array false none Links to the pages with company news articles on the company's website.
»» prh_crawled_date date-time false none Date that the Finnish patent registry was last crawled.
»» salary_board_local float false none Compensation the board of the company receives, as seen in the financial statement. In local currency.
»» contacts [object] false none All the contact details identified for the company.
»»» uid string false none Unique identifier issued by Vainu for the contact
»»» first_name string false none none
»»» last_name string false none none
»»» email string false none none
»»» phone string false none none
»»» title string false none none
»»» modified date-time false none Timestamp when contact data was last modified
»» profit float false none Profit for the company, as found in the financial statement.
»» industry_codes_local array false none All industry codes identified for the company that are predominantly used in the local market.
»» bookkeeping_firm_normalized string false none Normalized name for the company's accounting firm.
»» staff_number integer false none Company's employee count.
»» social_profiles array false none Company's social media handles in different social media channels.
»» owned_percent float false none none
»» mother_business_id_generic object false none Business id for the linked parent company of the organization.
»» city string false none City where the registered address is located.
»» bs_total_equity_local float false none Sum of total equity, as seen on the balance sheet. In local currency.
»» bs_total_equity_and_liab_local float false none Sum of total equity and liabilities, as seen on the balance sheet. In local currency.
»» address_count integer false none Total number of addresses found for the company.
»» industry_codes_main array false none none
»» dividend_local float false none Dividends paid out as seen on the balance sheet. In local currenty.
»» expiration_date date-time false none none
»» paye_register_date date-time false none none
»» deregistration_date date-time false none none
»» dissolution_successors array false none none
»» employee_salary float false none none
»» youtube_video_count integer false none Number of videos posted on the company's Youtube channel.
»» company_name_unofficial string false none Unofficial business names linked to the company.
»» visiting_municipality string false none County that the company's visiting address is located in.
»» facebook_likes integer false none Number of likes on the company's Facebook page.
»» turnover_estimate float false none Estimated revenue for the company.
»» industry_codes_other array false none none
»» bs_provisions float false none none
»» facebook_ptat integer false none People talking about this metric for the company's Facebook page.
»» area integer false none none
»» xbrl_current array false none none
»» turn_over_upperlimit float false none Upper limit of the company's revenue range, when applicable.
»» contact_page_urls array false none Links to the pages on company's website with contact information.
»» industry_codes_other_local array false none none
»» postal_int integer false none none
»» staff_number_lowerlimit integer false none Lower limit of the company's employee count range, when applicable.
»» development_of_turnover_class integer false none none
»» link string false none Website URL of the company.
»» linkedin_industry string false none Linkedin Industry of the company.
»» orginal_image string false none none
»» form_of_company_n array false none none
»» twitter_link string false none Link to the company's Twitter profile.
»» alexa_rank_reach integer false none none
»» instagram_link_count integer false none Number of links on the website to Instagram.
»» industry_description array false none Description of the industry code.
»» vainu_social_score float false none none
»» nstatus integer false none Whether the company is considered active or not (0 = active).
»» youtube_link string false none Link to the company's Youtube page.
»» payroll_overhead float false none Total costs of payroll, as found in the balance sheet.
»» industry_codes array false none All industry codes identified for the company.
»» linkedin_link string false none Link to the company's Linkedin profile.
»» kr_gross_profit_margin_percent float false none Percentage of gross profit out of total revenue.
»» alexa_rank_delta integer false none Change in the company's Alexa rank since the previous measuring date.
»» turnover_cls integer false none none
»» turn_over_local float false none Revenue of the company in local currency.
»» alexa_rank_country integer false none Country where the company's website is ranked according to Alexa.
»» youtube_comment_count integer false none Number of comments on videos posted on the company's Youtube page.
»» turn_over_lowerlimit float false none Lower limit of the company's revenue range, when applicable.
»» bs_total_assets_local float false none Sum of total assets as found on the balance sheet. In local currency.
»» crawled_datetime date-time false none Date that the original entity was crawled into the database.
»» stock_exchange string false none Location of the stock exchange the company is listed in.
»» e_invoice_addresses array false none The electronic invoice address of the company (Europe only).
»» turn_over float false none Exact revenue of the company.
»» equity_to_assets_ratio float false none The equity to assets ratio, as found on the balance sheet.
»» structure array false none none
»» bs_total_long_term_debts_local float false none The sum of total long term debts in the past year, as found on the balance sheet. In local currency.
»» facebook_link string false none Link to the facebook page of the company.
»» kr_quick_ratio_percent float false none Company's quick ratio as found on the balance sheet.
»» verified_domains array false none All verified website URLs for the company.
»» industry_code_crawled_date date-time false none Date the company industry codes were crawled.
»» content_career_page string false none Full text of the company's career page.
»» registry_url string false none Source for the original entity information from the business registry.
»» group_data object false none Details of the group and the highest entity in the group
»»» group_name string false none none
»»» turn_over_eur integer false none Combined turn over of the group
»»» staff_number integer false none Combined stuff number of the group
»»» group_parent_business_id string false none Business id of the highest entity in the group
»»» turn_over_local integer false none Combined turn over of the group
»»» group_parent_country string false none Country of the highest entity of the group
»»» group_parent_company_name string false none Name of the highest entity in the group
»»» countries [string] false none List of countries the group has companies in
»»» currency_code string false none Currency code of the highest entity in the group
»»» company_level integer false none none
»» related_links [object] false none none
»»» description string false none Snippet or description from the link source
»»» language_codes [string] false none Languages of the link source
»»» countries [string] false none none
»»» types [string] false none Type of the link source, eg. wikipedia
»»» link string false none Link to the source
»»» title string false none Title of the source
»» real_estate object false none Real estate data. Extra permission required.
»»» parking_spaces integer false none none
»»» heating_system string false none none
»»» roof_material string false none none
»»» energy_class string false none none
»»» floors_building integer false none none
»»» land_ownership string false none If the land is rented or owned
»»» land_owner string false none Owner of the land, if rental
»»» land_rental number false none Price per year
»»» land_size_building integer false none none
»»» building_year integer false none none
»»» construction_material string false none none
»»» roof_type string false none none
»»» commercial_apartments string false none none
»»» building_type string false none none
»»» building_apartment_count integer false none none
»»» amenities [string] false none none
»»» property_maintenance_company string false none none
»»» property_management_company string false none none
»»» renovations_done [string] false none none
»»» renovations_coming [string] false none none

Get Signals

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Accept': 'application/json',
  'API-Key': API_KEY
} 

r = requests.get('https://api.vainu.io/api/v2/signals/',
	params={},
	headers=headers
)

print(r.json())


curl -X GET https://api.vainu.io/api/v2/signals/ \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).

const headers = {
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/signals/',
{
  method: 'GET',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /signals/

Filtering

This endpoint requires at least one filter parameter.

See filtering.












Signals on 3rd of July, 2019, where the company is Finnish and has the industry code 87301:

https://api.vainu.io/api/v2/signals/?country=FI&industry_codes=87301&signals__datetime__gte=2019-07-03&signals__datetime__lt=2019-07-04

Filter by date

To filter signals from a date range, you should use the query parmeters signals__datetime__gte and signals__datetime__lt with a value in ISO8601 format. Other filters on date are not available.


Example responses

200 Response

{
  "results": [
    {
      "id": 251951671,
      "companies": [
        {
          "business_id": "25578642",
          "company_name": "Vainu. io Software Oy"
        },
        {
          "business_id": "28229966",
          "company_name": "Vainu Finland Oy"
        }
      ],
      "datetime": "2019-06-27T07:36:15.994",
      "title": "Software Developer (Python)",
      "link": "https://duunitori.fi/tyopaikat/tyo/software-developer-python-svsai-10535623",
      "tags": [
        "Open Positions"
      ],
      "vainu_link": "https://app.vainu.io/vainu/prospect/708216/",
      "content": "Tervehdys, sinä kymmeniä tuhansia koodirivejä kirjaillut, erilaisten APIen kanssa leikkinyt ja aitojen ongelmien ratkomisesta kiinnostunut koodari.\n\nVainu on yritystiedon koti. Me keräämme maailmasta kaiken yrityksiin liittyvän tiedon ja järjestämme sen. Sitten jalostamme sitä ja luomme uusia, avartavia datapisteitä. Kuten vaikkapa sen, että yritys tarvitsee vähäpäästöisen leasing-auton uudelle aluemyyjälleen. Tai että yrityksen pitäisi hankkia uudet nettisivut. SaaS-palveluamme hyödyntää jo yli 2000 yritysdataa tarvitsevaa puljua kansainvälisistä pörssiyrityksistä pk-firmoihin, viidessä eri maassa. Tuote syntyy kokonaisuudessaan Helsingin Kalliossa. \n\nJos tässä kohtaa ajattelet pölyistä yritysrekisteriä ja mietit, mitä kiinnostavaa sellaisessa on, voit raapaista Vainun pintaa täältä .\n\nIsossa kuvassa olemme vasta alussa. Hyödynnämme murto-osan niistä mahdollisuuksista, joita yritysdatan älykkäässä rikastamisessa piilee. Koodia on vielä kirjoitettavana.\n\nTavoitteemme on olla maailman hyödyllisin yritystietopalvelu. Matkaa jouduttaaksemme etsimme tech-tiimiimme vahvistuksia, joita voisi kuvata seuraavasti:\nVahva Python-osaaminen. #django\nPerusymmärrys tietokannoista ja tietokantakyselyistä. #mongodb\nAsenne, jolla ongelmien on yksinkertaisesti ratkettava.\nHalu oppia uutta ja tehdä asioita paremmin.\n\n \n\nTyökavereinasi on lahjakkaita koodareita ja designereita. Kulttuurimme on rehellinen, rohkea ja aikaansaava. Byrokratiaa ja turhaa hierarkiaa vältämme viimeiseen asti, joten mikäli nautit viikkopalavereita ja tikettijärjestelmiä, Vainu ei ehkä ole sinua varten.\n\nMikäli katsoit yo. videon ja bongasit jo pari asiaa, jotka haluaisit tehdä paremmin - tai näit vain itsesi koodaamassa Vainulla - laita viestiä alla olevan napin takaa, niin jutellaan lisää. Laita kyytipojaksi linkki johonkin projektiisi (esim. GitHub)."
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Company lists

Get company lists

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Accept': 'application/json',
  'API-Key': API_KEY
} 

r = requests.get('https://api.vainu.io/api/v2/lists/',
	params={},
	headers=headers
)

print(r.json())


curl -X GET https://api.vainu.io/api/v2/lists/ \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).

const headers = {
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/lists/',
{
  method: 'GET',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /lists/

Returns a list with all company lists. The lists can be created and modified in Vainu user interface.

Use the id of a list to filter companies and signals.

Example responses

200 Response

{
  "results": [
    {
      "id": "5e305b7a5c7ef8001673abc3",
      "name": "Bookmarks",
      "is_named_list": true,
      "default": true,
      "owner_email": "example@vainu.io",
      "added_companies": null
    },
    {
      "id": "5e9d9d1eb3f25e015cb1afc9",
      "name": "List 1",
      "is_named_list": true,
      "default": false,
      "owner_email": "example@vainu.io",
      "added_companies": null
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Create company lists

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'API-Key': API_KEY
} 
body = {
  "name": "List 1"
}
r = requests.post('https://api.vainu.io/api/v2/lists/',
	params={},
	json=body,
	headers=headers
)

print(r.json())


curl -X POST https://api.vainu.io/api/v2/lists/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY' \
  --data '{"name":"List 1"}'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).
const inputBody = {
  "name": "List 1"
};
const headers = {
  'Content-Type':'application/json',  
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/lists/',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /lists/

Create a new company list. To add companies, use put

Body parameter

{
  "name": "List 1"
}

Parameters

Name In Type Required Description
body body any false none

Example responses

200 Response

{
  "id": "5e9d9d1eb3f25e015cb1afc9",
  "name": "List 1",
  "is_named_list": true,
  "default": false,
  "owner_email": "example@vainu.io",
  "added_companies": null
}

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Update company lists

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'API-Key': API_KEY
} 
body = {
  "add_companies": [
    {
      "company_name": "vainu software",
      "country": "FI",
      "business_id": "25578642",
      "address": "Eteläesplanadi 12",
      "postal": "00130",
      "city": "Helsinki",
      "domain": "vainu.com"
    },
    {
      "company_name": "doesnt exist",
      "country": "FI"
    }
  ]
}
r = requests.put('https://api.vainu.io/api/v2/lists/{list_id}/',
	params={},
	json=body,
	headers=headers
)

print(r.json())


curl -X PUT https://api.vainu.io/api/v2/lists/{list_id}/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY' \
  --data '{"add_companies":"[object Object],[object Object]"}'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).
const inputBody = {
  "add_companies": [
    {
      "company_name": "vainu software",
      "country": "FI",
      "business_id": "25578642",
      "address": "Eteläesplanadi 12",
      "postal": "00130",
      "city": "Helsinki",
      "domain": "vainu.com"
    },
    {
      "company_name": "doesnt exist",
      "country": "FI"
    }
  ]
};
const headers = {
  'Content-Type':'application/json',  
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/lists/{list_id}/',
{
  method: 'PUT',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PUT /lists/{list_id}/

Update a company list.

To add companies to the list, use the parameters add_companies or replace_companies. replace_companies removes all previous companies and replace them with the given companies. add_companies adds the given companies to the already existing companies. Use replace_companies with an empty list to remove the companies in the list. The list of companies to add should include objects with datapoints about the company to be added. The matching uses the same logic as matching with the companies api and ´matching=true´

A maximum of 50 companies can be added with one request.

Note that companies will be matched to all countries for accurate matching, but filtering in the companies endpoint is only possible with the countries you have access to. It is important to include information on the country of the company for reliable matching.

The response includes a list of companies that will be added to the list, in the same order as in the request. If a match was not found, ´null´ is returned instead of a company.

Body parameter

{
  "add_companies": [
    {
      "company_name": "vainu software",
      "country": "FI",
      "business_id": "25578642",
      "address": "Eteläesplanadi 12",
      "postal": "00130",
      "city": "Helsinki",
      "domain": "vainu.com"
    },
    {
      "company_name": "doesnt exist",
      "country": "FI"
    }
  ]
}

Parameters

Name In Type Required Description
body body any false none

Example responses

200 Response

{
  "id": "5e9d9d1eb3f25e015cb1afc9",
  "name": "List 1",
  "is_named_list": true,
  "default": false,
  "owner_email": "example@vainu.io",
  "added_companies": [
    {
      "country": "FI",
      "company_name": "Vainu. io Software Oy",
      "business_id": "25578642"
    },
    null
  ]
}

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Delete company lists

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'API-Key': API_KEY
} 

r = requests.delete('https://api.vainu.io/api/v2/lists/{list_id}/',
	params={},
	headers=headers
)

print(r.json())


curl -X DELETE https://api.vainu.io/api/v2/lists/{list_id}/ \
  -H 'API-Key: API_KEY'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).

const headers = {
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/lists/{list_id}/',
{
  method: 'DELETE',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /lists/{list_id}/

Delete a company list.

Responses

Status Meaning Description Schema
200 OK OK None

Async requests

Async request

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Accept': 'application/json',
  'API-Key': API_KEY
} 

r = requests.get('https://api.vainu.io/api/v2/companies/async/',
	params={},
	headers=headers
)

print(r.json())


curl -X GET https://api.vainu.io/api/v2/companies/async/ \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).

const headers = {
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/companies/async/',
{
  method: 'GET',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /companies/async/

Asynchronous method for /companies. Preferred method for longer and more complex queries which may cause longer response times. Endpoint returns a job id with details for fetching the results when operation has completed.

Continuous requests to see the status of the job should be done with the link provided in the initial response. Results can be downloaded from the download_link in the response.

Initial status of the async job will be accepted. This status will be process for ongoing jobs and finally either completed or failure depending if the operation was Successful. Async endpoint supports Get and Post requests.

Example responses

200 Response

{
  "created": "2021-06-15T12:52:40.956353",
  "duration": "0.02",
  "download_link": "https://app.vainu.io/api/v2/async_result/public-companies-async-api/546ea42d-ea32/download/",
  "finished": null,
  "job_id": "546ea42d-ea32",
  "link": "https://app.vainu.io/api/v2/async_result/public-companies-async-api/546ea42d-ea32-49bc-96d6-5393a0498939/",
  "state": "accepted"
}

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» created date-time false none Timestamp when the job was created
» duration string false none Duration the job has been running
» download_link string false none Link where completed data may be requested
» finished date-time false none Timestamp when the job was completed
» job_id string false none Unique id for the job
» link string false none Link to request the status of the job. Response is identical to the initial request
» state string false none State of the job. Expected statuses are accepted, process, completed, and failure.

Customer data

Create Customer data object by matching with a company in Vainu

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'API-Key': API_KEY
} 
body = {
  "owner_email": "example@vainu.io",
  "unique_id": "f39a1a59",
  "won_deals_count": 2,
  "open_deals_count": 1,
  "lost_deals_count": 0,
  "notes": "string",
  "last_update": "2018-06-08",
  "match_data": {
    "company_name": "Vainu Finland Oy",
    "business_id": "2822996-6",
    "country": "FI"
  }
}
r = requests.post('https://api.vainu.io/api/v2/customer_data/',
	params={},
	json=body,
	headers=headers
)

print(r.json())


curl -X POST https://api.vainu.io/api/v2/customer_data/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY' \
  --data '{"owner_email":"example@vainu.io","unique_id":"f39a1a59","won_deals_count":"2","open_deals_count":"1","lost_deals_count":"0","notes":"string","last_update":"2018-06-08","match_data":"[object Object]"}'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).
const inputBody = {
  "owner_email": "example@vainu.io",
  "unique_id": "f39a1a59",
  "won_deals_count": 2,
  "open_deals_count": 1,
  "lost_deals_count": 0,
  "notes": "string",
  "last_update": "2018-06-08",
  "match_data": {
    "company_name": "Vainu Finland Oy",
    "business_id": "2822996-6",
    "country": "FI"
  }
};
const headers = {
  'Content-Type':'application/json',  
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/customer_data/',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /customer_data/

Save data into the object and match with a company in the Vainu database.

The Customer data object will be linked to a company based on the matching parameters that are included in the request body.

The company_info field includes information about the matched company. The returned fields can be changed with the fields parameter. These fields can only be changed for the response to matching. Any future requests will always only return the default fields.

The company_vid field will be -1 if a match is not found, and company_info will be null.

For more information on matching, see get-companies.

Body parameter

{
  "owner_email": "example@vainu.io",
  "unique_id": "f39a1a59",
  "won_deals_count": 2,
  "open_deals_count": 1,
  "lost_deals_count": 0,
  "notes": "string",
  "last_update": "2018-06-08",
  "match_data": {
    "company_name": "Vainu Finland Oy",
    "business_id": "2822996-6",
    "country": "FI"
  }
}

Parameters

Name In Type Required Description
body body #/components/schemas_hide/CustomerDataPost false none

Example responses

200 Response

{
  "owner_email": "example@vainu.io",
  "origin": "customerDataApi",
  "unique_id": "f39a1a59",
  "won": true,
  "won_deals_count": 2,
  "open_deals_count": 1,
  "lost_deals_count": 0,
  "notes": "string",
  "last_update": "2018-06-08",
  "modified": "2020-08-06T12:08:03.220",
  "created": "2020-08-06T12:08:03.219",
  "company_info": {
    "country": "FI",
    "domain": "vainu.com",
    "company_name": "Vainu Finland Oy",
    "vid": 463880794,
    "business_id": "28229966"
  },
  "id": "5f2bf2a35f171f0b0b0041cf",
  "company_vid": 463880794,
  "match_data": {
    "country": "FI",
    "company_name": "Vainu Finland Oy",
    "business_id": "2822996-6"
  }
}

Responses

Status Meaning Description Schema
200 OK OK Inline
400 Unknown Match parameter missing Inline
400 Unknown Invalid business id or insufficient country permissions Inline

Response Schema

Get multiple Customer data objects

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Accept': 'application/json',
  'API-Key': API_KEY
} 

r = requests.get('https://api.vainu.io/api/v2/customer_data/',
	params={},
	headers=headers
)

print(r.json())


curl -X GET https://api.vainu.io/api/v2/customer_data/ \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).

const headers = {
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/customer_data/',
{
  method: 'GET',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /customer_data/

Filtering

You can filter the results on the values of the fields. You can also append operators to the filters,
(for example ?won_deals_count__gte=3):

Ordering

Use the query parameter ordering to sort based on a field. A minus sign reverses the order. For example:

?ordering=-open_deals_count

Pagination

By default 100 results are shown per page. This can be modified by using the page_size parameter, and the page number can be specified with the page parameter. A maximum of 500 results per page is supported. Results include links to the next and previous pages, and null if no more pages are available.

Parameters

Name In Type Required Description
won_deals_count query integer false Filter
lost_deals_count query integer false Filter
open_deals_count query integer false Filter
won query boolean false Filter
unique_id query string false Filter
owner_email query string false Filter
last_update query string false Filter
prospect query string false Filter by vid

Example responses

200 Response

{
  "total_results": 1,
  "next_page": "https://api.vainu.io/api/v2/customer_data/?page=2",
  "prev_page": null,
  "results": [
    {
      "won": true,
      "origin": "PublicApi",
      "modified": "2018-06-09T12:30:39.923Z",
      "created": "2018-06-09T12:20:21.341Z",
      "prospect_info": {
        "vid": 463880794,
        "company_name": "Vainu Finland Oy",
        "business_id": "2822996-6",
        "country": "FI",
        "domain": "vainu.io"
      },
      "id": "2b1961522a6e7f19c3e5ac08",
      "prospect": 463880794
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK #/components/schemas_hide/Page
400 Bad Request Invalid query Inline

Response Schema

Get Customer data object by id

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Accept': 'application/json',
  'API-Key': API_KEY
} 

r = requests.get('https://api.vainu.io/api/v2/customer_data/{id}/',
	params={},
	headers=headers
)

print(r.json())


curl -X GET https://api.vainu.io/api/v2/customer_data/{id}/ \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).

const headers = {
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/customer_data/{id}/',
{
  method: 'GET',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /customer_data/{id}/

Get the Customer data object specified by the id.

Parameters

Name In Type Required Description
id path string true The id of the object to get

Example responses

200 Response

{
  "owner_email": "example@vainu.io",
  "origin": "customerDataApi",
  "unique_id": "f39a1a59",
  "won": true,
  "won_deals_count": 2,
  "open_deals_count": 1,
  "lost_deals_count": 0,
  "notes": "string",
  "last_update": "2018-06-08T00:00:00",
  "modified": "2020-08-06T12:08:03.220",
  "created": "2020-08-06T12:08:03.219",
  "company_info": {
    "country": "FI",
    "domain": "vainu.com",
    "company_name": "Vainu Finland Oy",
    "vid": 463880794,
    "business_id": "28229966"
  },
  "id": "5f2bf2a35f171f0b0b0041cf",
  "company_vid": 463880794,
  "match_data": {
    "country": "FI",
    "company_name": "Vainu Finland Oy",
    "business_id": "2822996-6"
  }
}

Responses

Status Meaning Description Schema
200 OK OK Inline
404 Not Found Not found None

Response Schema

Delete customer data object

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Accept': 'application/json',
  'API-Key': API_KEY
} 

r = requests.delete('https://api.vainu.io/api/v2/customer_data/{id}/',
	params={},
	headers=headers
)

print(r.json())


curl -X DELETE https://api.vainu.io/api/v2/customer_data/{id}/ \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).

const headers = {
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/customer_data/{id}/',
{
  method: 'DELETE',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /customer_data/{id}/

Deletes all Customer data objects that match the query. You can use the GET method with the same query parameters to see what would be deleted

NOTE: Use Vainu id instead of unique_id

Warning: Doing this without any query parameters will delete EVERY customer_data object you have access to!!

Parameters

Name In Type Required Description
id path string true The vainu id of the object.

Example responses

200 Response

{
  "deleted": 2
}

Responses

Status Meaning Description Schema
200 OK OK Inline
400 Bad Request Invalid query Inline

Response Schema

Status Code 200

Name Type Required Restrictions Description
» deleted integer false none none

Modify Customer data object

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Content-Type': 'application/json',
  'API-Key': API_KEY
} 
body = {
  "owner_email": "example@vainu.io",
  "unique_id": "f39a1a59",
  "won_deals_count": 2,
  "open_deals_count": 1,
  "lost_deals_count": 0,
  "notes": "string",
  "last_update": "2018-06-08",
  "match_data": {
    "company_name": "Vainu Finland Oy",
    "business_id": "2822996-6",
    "country": "FI"
  }
}
r = requests.patch('https://api.vainu.io/api/v2/customer_data/{id}/',
	params={},
	json=body,
	headers=headers
)

print(r.json())


curl -X PATCH https://api.vainu.io/api/v2/customer_data/{id}/ \
  -H 'Content-Type: application/json' \
  -H 'API-Key: API_KEY' \
  --data '{"owner_email":"example@vainu.io","unique_id":"f39a1a59","won_deals_count":"2","open_deals_count":"1","lost_deals_count":"0","notes":"string","last_update":"2018-06-08","match_data":"[object Object]"}'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).
const inputBody = {
  "owner_email": "example@vainu.io",
  "unique_id": "f39a1a59",
  "won_deals_count": 2,
  "open_deals_count": 1,
  "lost_deals_count": 0,
  "notes": "string",
  "last_update": "2018-06-08",
  "match_data": {
    "company_name": "Vainu Finland Oy",
    "business_id": "2822996-6",
    "country": "FI"
  }
};
const headers = {
  'Content-Type':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/customer_data/{id}/',
{
  method: 'PATCH',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

PATCH /customer_data/{id}/

Modify a Customer data object. If match parameters are included, will try to make a new match.

Body parameter

{
  "owner_email": "example@vainu.io",
  "unique_id": "f39a1a59",
  "won_deals_count": 2,
  "open_deals_count": 1,
  "lost_deals_count": 0,
  "notes": "string",
  "last_update": "2018-06-08",
  "match_data": {
    "company_name": "Vainu Finland Oy",
    "business_id": "2822996-6",
    "country": "FI"
  }
}

Parameters

Name In Type Required Description
id path string true The id of the object that needs to be modified.
body body #/components/schemas_hide/CustomerDataPost false none

Responses

Status Meaning Description Schema
200 OK OK None
404 Not Found Not found None

Webhook configuration

Example data sent in a POST request to given url, for webhook type company_change_webhook

{
  "data": {
      "status": "active",
      "domain": "vainu.com",
      "turn_over": 895766,
      "visiting_address": "Etel\u00e4esplanadi 12",
      "business_id": "25578642",
      "company_name": "Vainu. io Software Oy",
      "visiting_city": "HELSINKI",
      "visiting_postal": "00130",
      "staff_number": 12,
      "region": "FI-18"
    },
  "number_of_tries": 1,
  "type": "company_change_webhook",
  "unique_id": "123abc"
}

Create webhooks to send data to your own endpoint when an event is triggered in Vainu.

If the webhook request receives a response with a status code of 300 or over, it may be attempted again a limited number of times, until an acceptable status code is returned.

Available triggers:

Get Webhook configuration

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Accept': 'application/json',
  'API-Key': API_KEY
} 

r = requests.get('https://api.vainu.io/api/v2/webhook_configuration/',
	params={},
	headers=headers
)

print(r.json())


curl -X GET https://api.vainu.io/api/v2/webhook_configuration/ \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).

const headers = {
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/webhook_configuration/',
{
  method: 'GET',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

GET /webhook_configuration/

Returns a list of all webhook configurations.

Example responses

200 Response

{
  "results": [
    {
      "webhook_url": "https://www.example.com/webhook_endpoint",
      "query": "?crm=custom",
      "id": "5f5b7b3ebb9378063bc322ef",
      "username": "example@vainu.io",
      "type": "company_change_webhook"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Create Webhook configuration

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'API-Key': API_KEY
} 
body = {
  "webhook_url": "https://www.example.com/webhook_endpoint",
  "query": "?crm=custom",
  "type": "company_change_webhook"
}
r = requests.post('https://api.vainu.io/api/v2/webhook_configuration/',
	params={},
	json=body,
	headers=headers
)

print(r.json())


curl -X POST https://api.vainu.io/api/v2/webhook_configuration/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'API-Key: API_KEY' \
  --data '{"webhook_url":"https://www.example.com/webhook_endpoint","query":"?crm=custom","type":"company_change_webhook"}'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).
const inputBody = {
  "webhook_url": "https://www.example.com/webhook_endpoint",
  "query": "?crm=custom",
  "type": "company_change_webhook"
};
const headers = {
  'Content-Type':'application/json',  
  'Accept':'application/json',  
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/webhook_configuration/',
{
  method: 'POST',
  body: JSON.stringify(inputBody),
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

POST /webhook_configuration/

Create a webhook configuration.

Body parameter

{
  "webhook_url": "https://www.example.com/webhook_endpoint",
  "query": "?crm=custom",
  "type": "company_change_webhook"
}

Parameters

Name In Type Required Description
body body object false none
» webhook_url body string false The url to send requests to
» query body string false none
» type body string false none

Enumerated Values

Parameter Value
» type company_change_webhook

Example responses

200 Response

{
  "webhook_url": "https://www.example.com/webhook_endpoint",
  "query": "?crm=custom",
  "id": "5f5b7b3ebb9378063bc322ef",
  "username": "example@vainu.io",
  "type": "company_change_webhook"
}

Responses

Status Meaning Description Schema
200 OK OK Inline

Response Schema

Delete Webhook configuration

Code samples

import requests

API_KEY = 'your_api_key'  # from Vainu settings
headers = {
  'API-Key': API_KEY
} 

r = requests.delete('https://api.vainu.io/api/v2/webhook_configuration/{id}/',
	params={},
	headers=headers
)

print(r.json())


curl -X DELETE https://api.vainu.io/api/v2/webhook_configuration/{id}/ \
  -H 'API-Key: API_KEY'

const fetch = require('node-fetch');  // install node-fetch if not installed (npm install node-fetch).

const headers = {
  'API-Key':'API_KEY'    // replace API_KEY with your api key from Vainu settings 

};

fetch('https://api.vainu.io/api/v2/webhook_configuration/{id}/',
{
  method: 'DELETE',
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

DELETE /webhook_configuration/{id}/

Delete a webhook configuration.

Responses

Status Meaning Description Schema
200 OK OK None