API-Referenz

Vollständige REST-API-Dokumentation für die VynCo-Plattform für Schweizer Corporate Intelligence

Offizielle SDKs

VynCo veröffentlicht hauseigene Client-Bibliotheken für Python, TypeScript, Rust und .NET. Alle SDKs sind Open Source (Apache-2.0 oder MIT) und werden mit der jeweils aktuellen API-Version synchron gehalten.

pip install vynco

npm install @vynco/sdk

cargo add vynco

dotnet add package VynCo

Authentifizierung

Schreibende Endpoints erfordern einen Bearer-Token im Authorization-Header; die meisten lesenden Endpoints funktionieren unauthentifiziert im Free-Tarif. Zwei Token-Typen werden unterstützt:

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

Antwort-Header

Jede API-Antwort enthält gruppenspezifische Ratenlimit-Header sowie eine Request-ID für Support und Tracing. Das vollständige gruppenspezifische Ledger wird über diese Header bereitgestellt — der Antwort-Body enthält keine Nutzungsinformationen.

Unternehmen

Suchen und rufen Sie angereicherte Schweizer Unternehmensdatensätze aus dem Register ab. Der Datenbestand umfasst über 790'000 aktive Unternehmen — 41 Felder pro Datensatz, einschliesslich Registerdaten, Adresse, Geolocation, NOGA-Klassifikation, Sanktions-Flags und Übersetzungen.

Änderungen

Verfolgen Sie Mutationen im Register — Adressänderungen, Wechsel der Revisionsstelle, Kapitalerhöhungen, Änderungen im Verwaltungsrat. Lesezugriffe verbrauchen die Gruppe standard_read; siehe den Abschnitt Ratenlimits für die Kontingente pro Tarif.

Personen

Schlagen Sie Personen und ihre Verwaltungsratsmandate über das gesamte Register hinweg nach. Lesezugriffe verbrauchen die Gruppe standard_read.

Dossiers

Erzeugen Sie zitatverankerte KI-Dossiers. Das LLM emittiert [[obl:...]]-Tags, die gegen den Methodik-Knowledge-Graph aufgelöst werden, sodass jede Aussage auf eine registrierte Pflicht oder Evidenz-Zeile zurückverweist. Verfügbar im Professional-Tarif (Gruppe methodology_read).

Analytics

Führen Sie Machine-Learning-Analysen über das gesamte Schweizer Handelsregister aus — Clustering, Anomalie-Erkennung, Kohorten-Analyse. Alle Analytics-Endpoints erfordern den Starter-Tarif oder höher (Gruppe analytics_read).

Beziehungen

Navigieren Sie durch Mutter-/Tochter-Konzernstrukturen. Lesezugriffe verbrauchen die Gruppe standard_read.

News & Berichte

Rufen Sie Unternehmensnachrichten von SIX und öffentlichen Quellen sowie geparste Jahresfinanzberichte ab. Lesezugriffe verbrauchen die Gruppe standard_read.

Notizen & Tags

Versehen Sie Unternehmen mit team-bezogenen Notizen und Tags. Notizen unterstützen Typen (Note, Annotation, Rating, Flag) und Sichtbarkeitssteuerung. Tags ermöglichen eigene Kategorisierungen und Filter.

Notizen

Tags

Klassifikation & Fingerprint

Rufen Sie Branchen-Klassifikationen (GICS-artige Hierarchie) und berechnete Unternehmens-Fingerprints mit Schlüsselkennzahlen, Grössenkategorie und Profil-Zusammenfassung ab.

Vergleich

Vergleichen Sie zwei oder mehr Unternehmen in einer einzigen Anfrage nebeneinander (2–10 Unternehmen).

Watches & Benachrichtigungen

Beobachten Sie Unternehmen, um Benachrichtigungen zu erhalten, sobald Änderungen im Register erkannt werden. Watch-Verwaltung und Abruf von Benachrichtigungen sind Teil der Gruppe account.

Benachrichtigungseinstellungen

Screening

Screenen Sie Entitäten in einer einzigen Anfrage gegen SECO-Sanktionen, OpenSanctions (PEP-Listen) und FINMA-regulierte Entitäten. Liefert ein Risikoniveau und alle erkannten Treffer.

Auditor Intelligence

Fragen Sie Mandatsdauer-Daten der Revisionsstellen über das Schweizer Handelsregister hinweg ab. Identifizieren Sie Unternehmen mit langer Mandatsdauer für die ISS-Rotationsanalyse oder rufen Sie die vollständige Mandatshistorie für ein bestimmtes Unternehmen ab. Diese Endpoints sind öffentlich und erfordern keine Authentifizierung.

Unternehmensereignisse

Rufen Sie historische Änderungs-Ereignisse für ein Unternehmen ab, einschliesslich Wechsel der Revisionsstelle, Kapitalveränderungen, Wechsel von Organmitgliedern und mehr. Ereignisse folgen der CloudEvents-Spezifikation und enthalten Metadaten zu Schweregrad und Kategorie. Öffentlicher Lese-Endpoint.

Gespeicherte Suchen

Speichern Sie Suchfilter zur schnellen Wiederverwendung und planen Sie deren automatische Ausführung in täglichem, wöchentlichem oder monatlichem Rhythmus. Geplante Suchen erzeugen Benachrichtigungen, wenn neue Ergebnisse gefunden werden.

Wirtschaftliche Berechtigung

Verfolgen Sie die vollständige Kette der wirtschaftlich Berechtigten für jedes Schweizer Unternehmen. Der Endpoint löst Mutterentitäten rekursiv auf und liefert Eigentumsanteile auf jeder Ebene. Zirkuläre Eigentumsstrukturen werden erkannt und automatisch markiert. Verfügbar im Professional-Tarif (Gruppe methodology_read).

Risk v2

Risikobewertung des Methodik-Teams: 9-Faktoren-Beta-Bernoulli-Posteriors mit FATF-konformen Priors. Jeder Faktor weist seine Prior, Posterior, Gewichtung und stützenden Belege aus; der zusammengesetzte Score ist die gewichtete Log-Odds. Verfügbar im Professional-Tarif (Gruppe methodology_read).

KI-Intelligenz

KI-gestützte Endpoints für die Erstellung von Due-Diligence-Dossiers, natürlichsprachige Unternehmenssuche und multi-signal-basierte Risikobewertung. Dossier- und Such-Endpoints nutzen LLM-Inferenz; das algorithmische Risk Scoring ist multi-faktoriell. KI-Erstellung wird gegen die Gruppe expensive_ai gemessen.

KI-Vergleichsanalyse

Erzeugen Sie KI-gestützte vergleichende Mehrunternehmens-Analysen mit Verwaltungsrats-Überlappungsanalyse, Governance-Bewertung und Wettbewerbspositionierung. Vergleichen Sie bis zu 10 Unternehmen in einer einzigen Anfrage. Wird gegen die Gruppe expensive_ai gemessen.

Massenoperationen

Führen Sie Operationen auf mehreren Entitäten gleichzeitig aus. Bulk-Screening prüft mehrere Entitäten in einer einzigen Anfrage gegen Sanktionslisten. Der CSV-Watchlist-Import ermöglicht das massenhafte Hinzufügen von Unternehmen. Der feldgesteuerte Export erlaubt die genaue Auswahl der Spalten in Ihrem Download. Wird gegen die Gruppe bulk gemessen (Enterprise-Tarif).

Bulk-Exporte

Reichen Sie asynchrone Bulk-Export-Jobs im NDJSON- oder CSV-Format ein. Pollen Sie den Job-Status-Endpoint, bis der Export abgeschlossen ist, und rufen Sie die Daten anschliessend inline ab (bis zu 10 MB). Unterstützt Filterung nach Kanton, Status und Zeilenlimits. Wird gegen die Gruppe bulk gemessen.

Unternehmens-PDF

Erzeugen Sie ein herunterladbares PDF-Profil für jedes Schweizer Unternehmen. Das Dokument umfasst Registerübersicht, Änderungshistorie, Verwaltungsrats-Zusammensetzung, Angaben zur Revisionsstelle und Risikoindikatoren. Wählen Sie über Query-Parameter, welche Abschnitte enthalten sein sollen.

Einbettbares Widget

Betten Sie Live-Unternehmens-Übersichtskarten auf Partner-Websites ein. Zwei Integrationsmethoden werden unterstützt: ein JavaScript-Auto-Loader, der die Seite nach data-vynco-uid-Attributen scannt, oder eine direkte iframe-Einbettung. Beide Optionen unterstützen helles und dunkles Theme. Für öffentliche Widgets ist keine Authentifizierung erforderlich.

<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>

Branchenberichte

Greifen Sie auf KI-erzeugte Branchen-Intelligenzberichte mit LLM-Erzählung, Schlüsselkennzahlen, Top-Unternehmen und Trendanalyse zu. Berichte decken GICS-basierte Branchensektoren über das Schweizer Register hinweg ab. Listen Sie verfügbare Branchen auf oder rufen Sie einen detaillierten Bericht für einen bestimmten Sektor ab. Wird gegen die Gruppe expensive_ai gemessen.

Blog

Öffentliche Blog-Endpoints zum Auflisten und Abrufen veröffentlichter Beiträge. Keine Authentifizierung erforderlich. Filtern Sie nach Tag oder rufen Sie einen einzelnen Beitrag per Slug ab.

Export

Exportieren Sie Unternehmensdaten als Excel-Tabellen. Unterstützt gefilterte Exporte mit anpassbarer Feldauswahl. Verfügbar im Professional-Tarif (Gruppe bulk).

OpenAPI-Spezifikation

Die vollständige OpenAPI-3.0-Spezifikation (über 140 Endpoints) ist verfügbar für Selbstentdeckung, SDK-Generierung und Integration in Tools wie Postman, Insomnia oder Swagger UI. Zum Abruf der Spezifikation ist keine Authentifizierung erforderlich.

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

Verwaltung

Endpoints für Team-, API-Schlüssel- und Nutzungsverwaltung. Diese Lesezugriffe gehören zur Gruppe account und verfügen über ein grosszügiges tarifabhängiges Limit.

Teams

API-Schlüssel

Nutzung

Fehler-Referenz

Alle Fehlerantworten folgen dem RFC-7807-Problem-Details-Format mit konsistenter Struktur über alle Endpoints hinweg. Das Beispiel unten zeigt eine 429-Too-Many-Requests-Antwort — die häufigste Fehlerursache unter dem gruppenspezifischen Ratenlimit-Modell.

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
}

Ratenlimits

API-Anfragen sind je Endpoint-Gruppe und Tarif ratenlimitiert. Limits werden über die x-ratelimit-*-Antwort-Header bereitgestellt und am Ende jedes Zeitfensters zurückgesetzt. Wenn eine Anfrage ihr Bucket überschreitet, gibt die API 429 Too Many Requests mit einem Retry-After-Header zurück.

Related Articles