---
updatedAt: 2026-10-06T13:14:35.000Z
agentTools:
  projectIndex: https://developers.vainu.com/llms.txt
---

# Getting Started

Quick start guide to making your first API request with Vainu API

# Getting Started with Vainu API

## Your First Request

Let's get some company data from Organizations API.

First you need to Refresh Token that you can get by logging in to Vainu UI: <https://vainu.app/settings/api-access>

<Image src="https://files.readme.io/d37f0badff8f29fa7c86f45729c0822be861bf4a3c2b3d6e36a1f38ba716730d-Screenshot_2026-03-30_at_11.21.18.png" align="center" />

## Basic Request Structure

All API requests follow a consistent structure with the following main components:

```text Vainu CLI
vainu organizations --payload '{
  "query": {"?EQ": {"business_id": "FI05381340"}},
  "fields": ["business_id", "name", "legal_entity"],
  "database": "FI",
  "limit": 1
}'
```
```python Vainu CLI Python API
"""Simple Example: Get data of single business id using the vainu-cli Python API"""
import os
# Install from PyPI -- https://developers.vainu.com/docs/vainu-cli-python-api#pypi
from vainu_cli import VainuJWTSyncClient

# The classic JWT. The client exchanges the refresh token for a short-lived access token
# (and refreshes it when it expires). Set your refresh token to env or replace here:
client = VainuJWTSyncClient(refresh_token=os.environ.get("VAINU_REFRESH_TOKEN", "your-refresh-token"))

payload = {
    # Which companies?
    "query": {"?EQ": {"business_id": "FI05381340"}},
    # What data points are returned?
    "fields": [  # Add any fields from the data catalogue
        "business_id",
        "name",
        "legal_entity",
    ],
    # What country?
    "database": "FI",
    # How many results?
    "limit": 1,
}

try:
    print(client.organizations(payload=payload))
finally:
    client.close()
# Example response:
"""
[{'name': 'Kiitosimeon Oy', 'business_id': 'FI05381340', 'legal_entity': 'Osakeyhtiö'}]
"""
```
```python
"""Simple Example: Get data of single business id using organizations API"""
import requests
import os
organizations_endpoint_point = "https://api.vainu.io/api/v3/organizations/"
get_access_token_url = "https://api.vainu.io/api/token_authentication/refresh/"
# The classic JWT. Use refresh token to get short lived access token that is used to authenticate to the APIs. Set your refresh token to env or replace here:
refresh_token = os.environ.get("VAINU_REFRESH_TOKEN", "your-refresh-token")
# Get access token using refresh token:
access_token = requests.post(get_access_token_url, {"refresh": refresh_token}).json()["access"]


payload = {
    # Which companies?
    "query": {"?EQ": {"business_id": "FI05381340"}},
    # What data points are returned?
    "fields": [  # Add any fields from the data catalogue
        "business_id",
        "name",
        "legal_entity",  
    ],
    # What country?
    "database": "FI",
    # How many results?
    "limit": 1,
}

response = requests.post(
    organizations_endpoint_point,
    headers={"Authorization": f"Bearer {access_token}"},
    json=payload,
)
print(response.json())
# Example response:
"""
[{'name': 'Kiitosimeon Oy', 'business_id': 'FI05381340', 'legal_entity': 'Osakeyhtiö'}]
"""
```

<br />

<Recipe slug="simple-filtering-example-using-v3organizations" title="Simple Filtering Example Using Organizations API" />

## Key Request Parameters

### query

The filtering query using Vainu's Query Language. Learn more in the [Filtering Query Language](https://developers.vainu.com/docs/filtering-query-language) section.

```json
{
  "query": {
    "?EQ": {
      "official_industries.code": ["62"]
    }
  }
}
```
```text Vainu CLI
vainu organizations --payload '{
  "database": "FI",
  "query": {"?EQ": {"official_industries.code": ["62"]}},
  "fields": ["business_id", "name", "official_industries.code", "official_industries.description"],
  "limit": 3
}'
```

### database

The country database to query. Supported values:

* `FI` - Finland
* `SE` - Sweden
* `NO` - Norway
* `DK` - Denmark
* `NL`- Netherlands

### fields

Full data reference with hundreds of data points can be found in <https://vainu.app/data-catalogue/>

Some examples of basic fields:

* `business_id` - Company identifier
* `name` - Company name
* `domain` - Website domain
* `official_industries` - Official industry classification
* `business_units` - Company Business locations
* `contacts` - Contacts
* `financial_data` - Latest financial data like revenue amount of employees
* `financial_statements` - Companys yearly Financial Statements

<br />

### Limit , offset and pagination

Number of results to skip before returning results (for pagination). We recommend using async instead of pagination for getting a lot of data.

```json
# Get results 100-200
payload = {
    "query": {...},
    "database": "FI",
    "limit": 100,
    "offset": 100
```

### order

Sort order for results. Use `-` prefix for descending order:

```json
{
  "order": "-vainu_score"  // Sort with Vainus proprietary scoring. Best score first.
}
```

## Response Structure

The API returns a list of json objects:

```json
[
    {
      "business_id": "FI12345678",
      "name": "Example Company Oy",
      "domain": "example.com",
      "official_industries": [{'code': }, ...],
      "contacts": [{'email': }, ...]
    },
}
```

## Error Handling

The API returns standard HTTP status codes:

* `200 OK` - Request successful
* `400 Bad Request` - Invalid query or parameters
* `401 Unauthorized` - Invalid or missing authentication token
* `403 Forbidden` - Access denied
* `500 Server Error` - Internal server error

<br />

## Next Steps

* [Set up authentication](https://developers.vainu.com/docs/authentication) with JWT or Client Credentials
* Learn how to [filter companies](https://developers.vainu.com/docs/filtering-query-language) using advanced queries
* Explore [response format options](https://developers.vainu.com/docs/response-formats)
* For large queries, consider [asynchronous requests](https://developers.vainu.com/docs/asynchronous-requests)