Vainu API Free Trial

Get a Free Trial Token

➡️
Request Vainu API Free Trial from https://www.vainu.com/delivery-methods/api/

The trial token is perfect for:

Testing the API before purchasing
Evaluating Vainu data for your use case
Learning the API structure and capabilities
Prototyping integrations

JWT Authentication for Trial

Get Access Token and Use It to Get Data

# Install Vainu CLI https://developers.vainu.com/docs/vainu-cli
export VAINU_JWT_REFRESH_TOKEN='123...'   # your token free trial access token

# Simple example of using the APIv3 search endpoint:
vainu organizations-search \
  --search volvo \
  --database SE \
  --fields business_id,name,website \
  --limit 5

import os
import pprint

from vainu_cli import VainuJWTSyncClient

# Set your free trial access token to env VAINU_JWT_REFRESH_TOKEN
# export VAINU_JWT_REFRESH_TOKEN=...
client = VainuJWTSyncClient(refresh_token=os.environ["VAINU_JWT_REFRESH_TOKEN"])

payload = {
    "search": "volvo",
    "fields": ["business_id", "name", "website"],  # Any APIv3 fields from https://vainu.app/data-catalogue/
    "database": "SE",
    "limit": 5,
}

pprint.pprint(client.organizations_search(payload))
client.close()

"""Simple example of using the APIv3 search endpoint.

Fuzzy text search that finds companies from a single input: business id,
company name or website. Results are sorted by relevance. The Vainu web
application search bar uses this same endpoint.

Set your free trial access token to env VAINU_JWT_REFRESH_TOKEN
export VAINU_JWT_REFRESH_TOKEN=...
"""

import os
import pprint

import requests

# Exchange the refresh token for a short-lived access token
response = requests.post(
    "https://api.vainu.io/api/token_authentication/refresh/",
    data={"refresh": os.environ["VAINU_REFRESH_TOKEN"]},
    timeout=10,
)
response.raise_for_status()
access_token = response.json()["access"]

payload = {
    "search": "volvo",
    "fields": ["business_id", "name", "website"],  # Any APIv3 fields from https://vainu.app/data-catalogue/
    "database": "SE",
    "limit": 5,
}

response = requests.post(
    "https://api.vainu.io/api/v3/organizations/search/",
    headers={"Authorization": f"Bearer {access_token}"},
    json=payload,
    timeout=10,
)
pprint.pprint(response.json())
# Example output:
# [{'business_id': 'SE5560125790',
#   'name': 'Aktiebolaget Volvo',
#   'website': 'https://www.volvogroup.com/se/'},
#  {'business_id': 'SE5560743089',
#   'name': 'Volvo Personvagnar Aktiebolag',
#   'website': 'volvocars.com/se'},
#  ...]

Token Lifecycle

The access token is valid for 12 hours. Refresh it when expired using the refresh token.

Reference Authentication Overview

Trial Limitations

Trial tokens come with the following limitations:

Feature	Trial API	Full API
Lifetime	30 days	Unlimited
Response limit	Max 20 results per request	No limit. Even full databases can be fetched.
Endpoints	`/api/v3/organizations/` only	Full API access
Concurrent requests	1 request at a time	Up to 20 concurrent requests. (Increasing concurrent requests)
Rate limit	1,000 requests per week	Unlimited (tier-dependent)
Databases	Limited availability	FI, SE, NO, DK, NL

Example: Trial API Call

Make your first API call with trial token:

import requests

# 1. Get access token
REFRESH_TOKEN = "your_trial_refresh_token"
TOKEN_ENDPOINT = "https://api.vainu.io/api/token/refresh/"

token_resp = requests.post(TOKEN_ENDPOINT, json={"refresh": REFRESH_TOKEN})
access_token = token_resp.json()["access"]

# 2. Query companies
COMPANIES_ENDPOINT = "https://api.vainu.io/api/v3/organizations/"

payload = {
    "query": {"?EQ": {"industry_codes_local": ["62"]}},
    "database": "FI",
    "fields": ["business_id", "name", "domain"],
    "limit": 20  # Trial limit
}

headers = {
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json"
}

response = requests.post(COMPANIES_ENDPOINT, headers=headers, json=payload)
companies = response.json()["results"]

print(f"Found {len(companies)} software companies:")
for company in companies:
    print(f"  - {company['name']} ({company['domain']})")

Key Differences from Full API

Response Limit

Trial: Maximum 20 results per request

payload = {
    ...
    "limit": 20  # Max for trial
}

Full API: Up to full database exports

payload = {
    ...
    "limit": 100000
}

Rate Limiting

Trial: 1,000 requests per week total

Full API: Up to 5 concurrent requests with higher weekly limits

Concurrent Requests

Trial: 1 concurrent request only

# ✓ Allowed
response1 = requests.post(ENDPOINT, ...)
result1 = response1.json()  # Wait for response

# ✗ Not allowed (won't start until previous completes)
response2 = requests.post(ENDPOINT, ...)

Full API: Up to 5 concurrent requests

Upgrade from Trial

When ready to move to production:

Contact Vainu sales
Select appropriate pricing tier
Migrate to production API keys
Increase limits and get support

Common Trial Errors

Error: Rate Limit Exceeded

You've exceeded the 1,000 requests/week limit:

Status: 429 Too Many Requests
Error: Rate limit exceeded

Solution: Wait until next week or upgrade to full API.

Error: Query Exceeds 20 Results

Your limit is 20 results:

# Wrong - will fail
payload = {"limit": 100}

# Correct
payload = {"limit": 20}

Error: Endpoint Not Available

Trial only supports /api/v2/companies:

# Wrong - trial doesn't support this
endpoint = "https://api.vainu.io/api/v3/stats/"

# Correct - use v2
endpoint = "https://api.vainu.io/api/v3/organizations/"

After Trial Expires

When your 30-day trial expires:

Access tokens will become invalid
New token refresh will fail
You'll need to upgrade or request a new trial

Contact support if you need an extension.

Getting Help

During your trial:

Review API documentation in this guide
Check code examples and best practices
Contact support with questions
Join Community Vainu Community Slack

Next Steps

Explore Authentication methods
Learn about Filtering Query Language
Review Getting Started guide
Check Organizations API for search capabilities

Ready to get started? Get your free trial token now!