Response Formats

Vainu API supports multiple response formats to suit different use cases and integration scenarios.

Format Overview

Set Output Format of the API responses: Directly In the Request URL

To define the output format directly in the request URL, you can use the format query parameter

POST https://api.vainu.io/api/v3/organizations/?format=csv

POST https://api.vainu.io/api/v3/organizations/?format=jsonl

Set Output Format of the API responses: Accept Header

To specify the output format, set the Accept header to your desired MIME type (e.g., text/csv or application/json)

response = requests.post(
    ORGANIZATIONS_ENDPOINT,
    headers={
        "Authorization": f"Bearer {access_token}",
        "Accept": "text/csv",
    },
    json=payload,
)

Set Language of the API responses: Accept-Language

Certain fields, such as official_industries.description support localization via the Accept-Language header

Available languages

response = requests.post(
    ORGANIZATIONS_ENDPOINT,
    headers={
        "Authorization": f"Bearer {access_token}",
        "Accept-Language": "sv",
        "Accept": "text/csv",
    },
    json=payload,
)

JSON (Default)

JSON is the default response format for all API endpoints.

Response Structure

[
    {
        "business_id": "SE12345678",
        "name": "Example Company AS",
        "domain": "example.com",
    },
    {
        "business_id": "SE23456781",
        "name": "Second example company AS",
        "domain": "secondexample.com",
    }
]

Dateformat ISO 8601

Streaming Formats

Streaming formats like JSONL and CSV are optimized for large datasets.

JSONL (JSON Lines)

One JSON object per line, ideal for streaming and line-by-line processing.

{"business_id": "FI12345678", "name": "Company 1", ...}
{"business_id": "FI87654321", "name": "Company 2", ...}

Usage:

# Process line by line
with open("results.jsonl") as f:
    for line in f:
        record = json.loads(line)
        # Process record

CSV (Comma-Separated Values)

Standard CSV format for spreadsheet applications.

• format=csv, fields must be spesified with full path
• Use headers to set custom headers. List must same length as fields.

payload = {
    "query": {...},
    "database": "FI",
    "headers": ["Business ID", "Company Name", "Website domain", "Employee count"],
    "fields": [
      "business_id",
      "name",
      "domain",
      "financial_data.employees.absolute_count",
    ],
    "limit": 2,
}

response = requests.post(
    "https://api.vainu.io/api/v3/organizations/?format=csv",  # or "json", "jsonl", "xlsx"
    headers={"Authorization": f"Bearer {access_token}"},
    json=payload
)
print(response.text)

Output:

"Business ID";"Company Name";"Website domain";"Employee count"
"SE1234567891";"Example Company AB";"";0
"SE2345678912";"Another Corp AB";"microdialysis.com";6

Asynchronous Format Selection

When using async endpoints, specify the format using the async_format GET parameter:

payload = {
    "query": {...},
    "database": "FI",
    "fields": ["business_id", "name", "domain"],
    "limit": 100000,
}

response = requests.post(
    "https://api.vainu.io/api/v3/organizations/async/?async_format=csv",  # or "json", "jsonl", "xlsx"
    headers={"Authorization": f"Bearer {token}"},
    json=payload
)

# Response includes download_link
job_info = response.json()
download_url = job_info["download_link"]

Format Selection Guide

Use JSON for:

• Single-page API responses
• Real-time integrations
• Structured data parsing
• API-to-API integrations

Use JSONL for:

• Streaming data processing
• Large file handling
• Line-by-line processing
• Storage in databases

Use CSV for:

• Excel spreadsheet import
• Business intelligence tools
• Data warehouse ingestion
• Easy human review

Use XLSX for:

• Direct Excel import
• Formatted spreadsheets
• Client deliverables
• Business reports

Handling Large Responses

For large datasets:

1. Use async endpoints - They handle long-running queries
2. Choose streaming format - CSV, JSONL for efficiency
3. Stream the response - Don't load entire file in memory

⚠️

The synchronous endpoint has a 2-minute timeout. For queries that might exceed this, use the asynchronous /async/ endpoint.