API Reference

Complete REST API documentation for the VynCo Swiss corporate intelligence platform

Official SDKs

VynCo publishes first-party client libraries for Python, TypeScript, Rust, and .NET. All SDKs are open source (Apache-2.0 or MIT) and kept in sync with the latest API version.

pip install vynco

npm install @vynco/sdk

cargo add vynco

dotnet add package VynCo

Authentication

Write endpoints require a Bearer token in the Authorization header; most read endpoints work unauthenticated against the Free tier. Two token types are supported:

curl "https://vynco.ch/api/v1/companies?search=Nestl%C3%A9" \
  -H "Authorization: Bearer vc_live_abc123..."

Response Headers

Every API response includes per-group rate-limit headers and a request ID for support and tracing. The full per-group ledger is exposed via these headers — there is no usage info in the response body.

Companies

Search and retrieve enriched Swiss company records from the registry. The dataset covers 790'000+ active companies — 41 fields per record including registry data, address, geolocation, NOGA classification, sanctions flags, and translations.

Changes

Track registry mutations — address changes, auditor changes, capital increases, board member updates. Reads consume the standard_read group; see the Rate Limits section for per-tier quotas.

Persons

Look up individuals and their board memberships across the registry. Reads consume the standard_read group.

Dossiers

Generate citation-anchored AI dossiers. The LLM emits [[obl:...]] tags resolved against the methodology knowledge graph, so every claim links back to a registered obligation or evidence row. Available on the Professional tier (methodology_read group).

Analytics

Run machine-learning analytics on the full Swiss company registry — clustering, anomaly detection, cohort analysis. All analytics endpoints require Starter tier or above (analytics_read group).

Relationships

Navigate parent/subsidiary corporate structures. Reads consume the standard_read group.

News & Reports

Fetch company news from SIX and public sources, plus parsed annual financial reports. Reads consume the standard_read group.

Notes & Tags

Annotate companies with team-scoped notes and tags. Notes support types (Note, Annotation, Rating, Flag) and privacy controls. Tags enable custom categorisation and filtering.

Notes

Tags

Classification & Fingerprint

Retrieve industry classifications (GICS-style hierarchy) and computed company fingerprints with key metrics, size category, and profile summary.

Comparison

Compare two or more companies side-by-side in a single request (2–10 companies).

Watches & Notifications

Watch companies to receive notifications when registry changes are detected. Watch management and notification retrieval are part of the account group.

Notification Preferences

Screening

Screen entities against SECO sanctions, OpenSanctions (PEP lists), and FINMA regulated entities in a single request. Returns a risk level and any matched hits.

Auditor Intelligence

Query auditor tenure data across the Swiss commercial registry. Identify companies with long auditor tenures for ISS rotation analysis, or retrieve the full auditor appointment history for a specific company. These endpoints are public and do not require authentication.

Company Events

Retrieve historical change events for a company including auditor changes, capital changes, officer changes, and more. Events follow the CloudEvents specification and include severity and category metadata. Public read endpoint.

Saved Searches

Save search filters for quick re-use and schedule them to run automatically on a daily, weekly, or monthly cadence. Scheduled searches generate notifications when new results are found.

Beneficial Ownership

Trace the full beneficial-ownership chain for any Swiss company. The endpoint recursively resolves parent entities and returns ownership percentages at each level. Circular ownership structures are detected and flagged automatically. Available on the Professional tier (methodology_read group).

Risk v2

Methodology-team risk score: 9-factor Beta-Bernoulli posteriors with FATF-aligned priors. Each factor exposes its prior, posterior, weight, and supporting evidence; the composite score is the weighted log-odds. Available on the Professional tier (methodology_read group).

AI Intelligence

AI-powered endpoints for due diligence dossier generation, natural-language company search, and multi-signal risk assessment. Dossier and search endpoints use LLM inference; algorithmic risk scoring is multi-factor. AI generation is metered against the expensive_ai group.

AI Comparative

Generate AI-powered multi-company comparative analysis with board-overlap detection, governance scoring, and competitive positioning. Compare up to 10 companies in a single request. Metered against the expensive_ai group.

Bulk Operations

Perform operations on multiple entities at once. Bulk screening checks multiple entities against sanctions lists in a single request. CSV watchlist import lets you add companies in bulk. Field-selected export lets you choose exactly which columns to include in your download. Metered against the bulk group (Enterprise tier).

Bulk Exports

Submit asynchronous bulk export jobs in NDJSON or CSV format. Poll the job status endpoint until the export completes, then retrieve the data inline (up to 10 MB). Supports filtering by canton, status, and row limits. Metered against the bulk group.

Company PDF

Generate a downloadable PDF profile for any Swiss company. The document includes registry overview, change history, board composition, auditor details, and risk indicators. Select which sections to include via query parameter.

Embeddable Widget

Embed live company summary cards on partner websites. Two integration methods are supported: a JavaScript auto-loader that scans the page for data-vynco-uid attributes, or a direct iframe embed. Both options support light and dark themes. No authentication required for public widgets.

<script src="https://vynco.ch/api/v1/widget/embed.js"></script>
<div data-vynco-uid="CHE-105.962.875"></div>

<iframe src="https://vynco.ch/api/v1/widget/company/CHE-105.962.875?theme=light&fields=name,canton,capital,status"
        width="400" height="200" frameborder="0"></iframe>

Industry Reports

Access AI-generated industry intelligence reports with LLM narrative, key statistics, top companies, and trend analysis. Reports cover GICS-based industry sectors across the Swiss registry. List available industries or retrieve a detailed report for a specific sector. Metered against the expensive_ai group.

Blog

Public blog endpoints for listing and retrieving published posts. No authentication required. Filter by tag or retrieve a single post by slug.

Export

Export company data as Excel spreadsheets. Supports filtered exports with customisable field selection. Available on the Professional tier (bulk group).

OpenAPI Specification

The full OpenAPI 3.0 specification (140+ endpoints) is available for self-discovery, SDK generation, and integration with tools like Postman, Insomnia, or Swagger UI. No authentication is required to fetch the spec.

curl "https://api.vynco.ch/api/v1/openapi.json"

Management

Team, API key, and usage management endpoints. These reads are part of the account group and have a generous per-tier limit.

Teams

API Keys

Usage

Error Reference

All error responses follow the RFC 7807 Problem Details format with consistent structure across all endpoints. The example below shows a 429 Too Many Requests response — the most common failure mode under the per-group rate-limit model.

HTTP/1.1 429 Too Many Requests
Retry-After: 3540
x-ratelimit-group: methodology_read
x-ratelimit-window: 1h
x-ratelimit-limit: 600
x-ratelimit-remaining: 0
x-ratelimit-reset: 3540
{
  "type": "https://api.vynco.ch/errors/rate-limit-exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded for the methodology_read group on the Professional tier (600/h). Honour the Retry-After header.",
  "instance": "/v1/dossiers/CHE-109.322.551",
  "group": "methodology_read",
  "window": "1h",
  "limit": 600,
  "retryAfterSeconds": 3540
}

Rate Limits

API requests are rate-limited per endpoint group, per tier. Limits are exposed via the x-ratelimit-* response headers and reset at the end of each window. When a request exceeds its bucket, the API returns 429 Too Many Requests with a Retry-After header.

Related Articles