Response data and format

Response format

Vainu API responds in JSON by default. Another option for response data is newline JSON (JSONL). The response data format can be changed by format parameter. JSONL can be a more efficient data format especially for larger datasets requested from an async endpoint.

Defining the data you need

Vainu's database has many different data fields for each company. It's usually efficient to state which data fields you would like to receive in the response right in the query. This can be achieved with the fields parameter.

There are three ways to utilize fields parameter. You can either specify fields to return, leave it out for default response and use all to get every data field available.

Fields parameterResponse
NoneDefault response
fields=allAll data available
fields=defaultDefault response, may be combined with other specified fields
fields=business_id,company_name,turn_overSpecified data fields

πŸ“˜

Subdocuments

Subdocuments can be requested with dot-notation. For example financial_statements.turn_over_eur would target all turn_over_eur fields found in financial statements.

Examples of defining fields to return

Examples of using different options on fields parameter.

# Default response
https://api.vainu.io/api/v2/companies/?business_id=NO918443525

# Default response with vainu custom industry
https://api.vainu.io/api/v2/companies/?business_id=NO918443525&fields=default,vainu_custom_industry

# Return all fields
https://api.vainu.io/api/v2/companies/?business_id=NO918443525&fields=all

# Return company name, turn over and domain
https://api.vainu.io/api/v2/companies/?business_id=NO918443525&fields=company_name,turn_over,domain

# Response in JSONL
https://api.vainu.io/api/v2/companies/?country=FI&format=jsonl&limit=1000

# Subdocuments
https://api.vainu.io/api/v2/companies/?company_name__startswith=vainu
&country=FI
&fields=business_id,financial_statements.turn_over_eur,financial_statements.year,
financial_statements.profit,addresses.address