Riferimento API

Documentazione REST API completa per la piattaforma VynCo di intelligence sulle aziende svizzere

Official SDKs

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

pip install vynco

npm install @vynco/sdk

cargo add vynco

dotnet add package VynCo

Authentication

All API requests require a Bearer token in the Authorization header. 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 the following headers for observability, OGD compliance, and credit tracking.

Companies

Search and retrieve Swiss company data from the Zefix registry. Each lookup or search costs 1 credit; enriched profiles cost 5 credits.

Changes

Track registry mutations — address changes, auditor changes, capital increases, board member updates. Each change feed query costs 2 credits.

Persons

Look up individuals and their board memberships across the registry. Person lookups cost 3 credits.

Dossiers

Generate AI-powered company dossiers using an LLM with full access to registry data, change history, and enrichment. Credit cost depends on the dossier level.

Analytics

Run machine-learning analytics on the full Swiss company registry. Clustering costs 15 credits, anomaly detection costs 15 credits, and cohort analysis costs 20 credits. All analytics endpoints require the Professional tier or above.

Relationships

Navigate parent/subsidiary corporate structures. Each relationships or hierarchy query costs 10 credits.

News & Reports

Fetch company news from SIX and public sources (2 credits per company, 1 credit for the global feed) and parsed annual financial reports (5 credits per company).

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. These operations do not consume credits.

Notes

Tags

Classification & Fingerprint

Retrieve industry classifications (GICS-style hierarchy) and computed company fingerprints with key metrics, size category, and profile summary. Classification costs 1 credit; fingerprints cost 2 credits.

Comparison

Compare two or more companies side-by-side in a single request. Costs 5 credits per request regardless of the number of companies compared (2–10).

Watches & Notifications

Watch companies to receive notifications when registry changes are detected. Watch management and notification retrieval do not consume credits.

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.

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. CRUD operations do not consume credits; running a search costs the same as a regular company search.

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. Costs 10 credits per request.

Predictive Risk

Predict company dissolution risk using a 7-signal model that analyses capital trends, auditor stability, board turnover, address changes, legal form risk, company age, and SOGC publication frequency. Returns a weighted composite score from 0 (no risk) to 100 (highest risk). Costs 10 credits per request.

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; risk scoring is purely algorithmic with six weighted factors.

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. Costs 25 credits per request.

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.

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.

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. Costs 5 credits per request.

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 68 GICS-based industry sectors across the Swiss registry. List available industries or retrieve a detailed report for a specific sector. Reports cost 15 credits.

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. Requires the Professional tier or above. Costs 10 credits per export.

OpenAPI Specification

The full OpenAPI 3.0 specification (v2.0.0, 99 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 credit management endpoints. These operations do not consume credits.

Teams

API Keys

Credits

Error Reference

All error responses follow the RFC 7807 Problem Details format with consistent structure across all endpoints.

{
  "type": "https://api.vynco.ch/errors/insufficient-credits",
  "title": "Insufficient Credits",
  "status": 402,
  "detail": "This request requires 50 credits but only 12 remain.",
  "instance": "/v1/dossiers",
  "creditsRequired": 50,
  "creditsAvailable": 12
}

Rate Limits

API requests are rate-limited per tier. When you exceed your limit, the API returns a 429 Too Many Requests response with a Retry-After header. The current limit is also returned in every response via X-Rate-Limit-Limit.

Related Articles