vynco

Python SDK for the VynCo Swiss Corporate Intelligence API. Access 780,000+ Swiss companies from the commercial register with historical timelines, change tracking, sanctions screening, AI-powered risk analysis, UBO resolution, network graphs, watchlists, webhooks, market-flow analytics, and bulk data exports.

Installation

pip install vynco

Or with uv:

uv add vynco

Quick Start

import vynco

client = vynco.Client("vc_live_your_api_key")

# Search the Swiss commercial register
result = client.companies.list(query="UBS", canton="BS")
uid = result.data.items[0].uid

# Get a single company
company = client.companies.get(uid)
print(f"{company.data.name} ({company.data.legal_form})")

# Full company details with persons, changes, relationships
full = client.companies.get_full(uid)
print(f"Board: {len(full.data.persons)} persons, {len(full.data.recent_changes)} recent changes")

# Historical timeline — every change the company ever made
timeline = client.companies.timeline(uid)
print(f"Timeline: {timeline.data.total_events} events")

# UBO resolution — identify ultimate beneficial owners
ubo = client.companies.ubo(uid)
print(f"UBO persons: {len(ubo.data.ubo_persons)} (chain depth: {ubo.data.chain_depth})")

# Sanctions screening (batch — up to 100 UIDs in one call)
batch = client.screening.batch(uids=[uid, "CHE-101.049.653"])
for r in batch.data.results:
    print(f"  {r.company_name}: {r.risk_level} ({r.total_hits} hits)")

# AI risk score
risk = client.ai.risk_score(uid=uid)
print(f"Risk: {risk.data.overall_score}/100 ({risk.data.risk_level})")

# Industry benchmarking — percentile ranks vs industry peers
bench = client.analytics.benchmark(uid=uid)
for d in bench.data.dimensions:
    print(f"  {d.name}: {d.percentile:.0f}th percentile")

Async Usage

import vynco

async def main():
    async with vynco.AsyncClient("vc_live_your_api_key") as client:
        result = await client.companies.list(query="Novartis")
        print(result.data.items[0].name)

Examples and Notebooks

The examples/ directory contains runnable scripts for common workflows. The notebooks/ directory contains Jupyter notebooks that produce publication-ready charts.

See examples/README.md and notebooks/README.md for details.

API Coverage

20 resource modules covering 100+ endpoints:

New in v3.1

• Historical timeline — companies.timeline() and AI narrative via companies.timeline_summary()
• Similar companies — companies.similar() scored on industry, canton, capital, legal form, auditor tier
• UBO resolution — companies.ubo() walks the ownership chain and identifies natural persons
• Ownership trace — ownership.trace() exposes the full chain with circular-ownership detection
• Media with sentiment — companies.media() filtered by positive/neutral/negative
• Batch operations — screening.batch() (up to 100 UIDs) and ai.risk_score_batch() (up to 50 UIDs)
• Market analytics — analytics.flows(), analytics.migrations(), analytics.benchmark()
• Person network — persons.network() for person-centric investigations with co-directors
• Saved alerts — persistent saved queries with optional webhook delivery
• Pagination on board_members — pass page= and page_size= (max 500)
• Typed hierarchy — HierarchyResponse now uses HierarchyEntity (was Any)
• Enriched watchlists — WatchlistCompaniesResponse.companies includes name/status/canton
• export_csv — new canonical name (export_excel kept as a deprecated alias)

Response Metadata

Every response includes header metadata for request tracing and rate limiting:

resp = client.companies.get("CHE-101.329.561")

print(f"Request ID: {resp.meta.request_id}")               # X-Request-Id
print(f"Rate group: {resp.meta.rate_limit_group}")         # X-RateLimit-Group
print(f"Rate window: {resp.meta.rate_limit_window}")        # X-RateLimit-Window
print(f"Rate limit: {resp.meta.rate_limit_limit}")          # X-RateLimit-Limit
print(f"Rate remaining: {resp.meta.rate_limit_remaining}")  # X-RateLimit-Remaining
print(f"Rate reset: {resp.meta.rate_limit_reset}")          # X-RateLimit-Reset
print(f"Data source: {resp.meta.data_source}")              # X-Data-Source

Configuration

client = vynco.Client(
    api_key="vc_live_xxx",
    base_url="https://vynco.ch/api",  # default
    timeout=30.0,                     # seconds, default
    max_retries=2,                    # default, retries on 429/5xx
)

The API key can also be set via the VYNCO_API_KEY environment variable:

export VYNCO_API_KEY=vc_live_your_api_key

client = vynco.Client()  # reads from VYNCO_API_KEY

The client automatically retries on HTTP 429 (rate limited) and 5xx (server error) with exponential backoff (500ms x 2^attempt). It respects the Retry-After and X-RateLimit-Reset headers when present.

Error Handling

All API errors are mapped to typed exceptions:

try:
    company = client.companies.get("CHE-000.000.000")
except vynco.AuthenticationError:
    print("Invalid API key")
except vynco.InsufficientCreditsError:
    print("Top up credits")
except vynco.ForbiddenError:
    print("Insufficient permissions")
except vynco.NotFoundError as e:
    print(f"Not found: {e.detail}")
except vynco.ValidationError as e:
    print(f"Bad request: {e.detail}")
except vynco.ConflictError:
    print("Resource conflict")
except vynco.RateLimitError:
    print("Rate limited, retry later")
except vynco.ServiceUnavailableError:
    print("AI backend temporarily unavailable")
except vynco.ServerError:
    print("Server error")
except vynco.VyncoError as e:
    print(f"Error ({e.status}): {e.detail}")

Requirements

• Python 3.11+
• httpx (async + sync HTTP)
• Pydantic v2 (model validation)

Development

uv sync                     # install dependencies
uv run pytest               # run tests
uv run ruff check src/      # lint
uv run ruff format src/     # format
uv run mypy src/            # type check

License

Apache-2.0