Quickstart Guide

Create a free VynCo account — no credit card required. Then navigate to the API Keys page in your dashboard and create a new key. The Free tier includes 60 search/h and 60 standard/h to explore the API at no cost.

Use GET /companies to search the Zefix registry. Pass a company name in the search parameter. Each lookup counts as one search_read request against your rate limit.

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

Narrow results by canton and changed_since timestamp. Combine multiple filters in a single request.

# Filter by canton
curl "https://vynco.ch/api/v1/companies?canton=ZH&pageSize=10" \
  -H "Authorization: Bearer vc_live_abc123..."
# Filter by canton and changed_since
curl "https://vynco.ch/api/v1/companies?canton=GE&changed_since=2025-01-01T00:00:00Z" \
  -H "Authorization: Bearer vc_live_abc123..."

Fetch the full profile of a specific company using its UID (format: CHE-xxx.xxx.xxx). Enriched profiles include share capital, industry, and auditor category — available on the Starter tier and above.

curl "https://vynco.ch/api/v1/companies/CHE-109.322.551" \
  -H "Authorization: Bearer vc_live_abc123..."

{
  "uid": "CHE-109.322.551",
  "name": "Nestlé S.A.",
  "canton": "VD",
  "status": "Active",
  "legalForm": "Aktiengesellschaft",
  "shareCapital": 322000000,
  "currency": "CHF",
  "industry": "Food Products",
  "auditorName": "KPMG AG",
  "auditorCategory": "state-supervised",
  "enrichmentLevel": "Enriched",
  "updatedAt": "2026-04-12T05:01:50Z"
}

Inspect every per-group rate-limit bucket for your API key with GET /v1/usage/current. This call does not consume a request from any other quota. Every API response also returns x-ratelimit-* headers so you can monitor remaining capacity per call.

curl "https://vynco.ch/api/v1/usage/current" \
  -H "Authorization: Bearer vc_live_abc123..."

{
  "tier": "starter",
  "groups": [
    { "group": "search_read",      "used": 412,  "limit": 600,  "window": "hour", "resetSeconds": 1842 },
    { "group": "standard_read",    "used": 86,   "limit": 600,  "window": "hour", "resetSeconds": 1842 },
    { "group": "analytics_read",   "used": 5,    "limit": 60,   "window": "hour", "resetSeconds": 1842 },
    { "group": "methodology_read", "used": null, "limit": null, "window": "hour", "resetSeconds": 1842 },
    { "group": "expensive_ai",     "used": null, "limit": null, "window": "day",  "resetSeconds": 51234 },
    { "group": "bulk",             "used": null, "limit": null, "window": "day",  "resetSeconds": 51234 }
  ]
}

HTTP/2 200
content-type: application/json
x-ratelimit-group: search_read
x-ratelimit-window: hour
x-ratelimit-limit: 600
x-ratelimit-remaining: 187
x-ratelimit-reset: 1746527200
x-request-id: req_01HZJ8K3...

Once you have data flowing, unlock deeper insights with the analytics endpoints. Run POST /analytics/cluster for K-Means or GMM clustering, POST /analytics/anomalies for anomaly detection, or GET /analytics/cohorts for cohort breakdowns by canton, legal form, founding year, or auditor. These calls count against analytics_read and require the Starter tier or above.

# Run K-Means clustering on Zurich companies
curl -X POST "https://vynco.ch/api/v1/analytics/cluster" \
  -H "Authorization: Bearer vc_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"algorithm":"kmeans","k":5,"canton":"ZH"}'

# Cohort analysis grouped by legal form
curl "https://vynco.ch/api/v1/analytics/cohorts?groupBy=legal_form" \
  -H "Authorization: Bearer vc_live_abc123..."

Use POST /v1/screening to screen an entity against SECO sanctions, OpenSanctions (PEP lists), and FINMA regulated entities in a single request. The response includes a risk level and any matched hits.

# Screen an entity against SECO, OpenSanctions, and FINMA
curl -X POST "https://vynco.ch/api/v1/screening" \
  -H "Authorization: Bearer vc_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Nestlé SA","sources":["seco","finma","opensanctions"]}'

{
  "queryName": "Nestlé SA",
  "queryUid": null,
  "screenedAt": "2026-03-30T10:00:00Z",
  "hitCount": 0,
  "riskLevel": "clear",
  "hits": [],
  "sourcesChecked": ["seco", "finma", "opensanctions"]
}

Use GET /v1/auditor-tenures to list companies with long auditor tenures. Set min_years=10 to find ISS rotation candidates. This endpoint is public and does not require authentication.

# Find companies with auditor tenures >= 10 years (ISS rotation candidates)
# This endpoint is public — no authentication required
curl "https://vynco.ch/api/v1/auditor-tenures?min_years=10&canton=ZH&pageSize=10"

{
  "items": [
    {
      "companyUid": "CHE-105.805.080",
      "companyName": "Nestlé SA",
      "auditorName": "KPMG AG",
      "appointedAt": "2004-01-15",
      "tenureYears": 22.2,
      "isCurrent": true,
      "source": "sogc"
    }
  ],
  "total": 206,
  "page": 1,
  "pageSize": 10
}

The full OpenAPI 3.0 specification is available at GET /api/v1/openapi.json — no authentication required. Use it to generate typed SDKs, import into Postman or Insomnia, or browse with Swagger UI. All endpoints, parameters, response schemas, and rate-limit groups are machine-readable.

# Download the full OpenAPI 3.0 spec (no auth required)
curl "https://api.vynco.ch/api/v1/openapi.json" -o openapi.json

You have made your first VynCo API calls. Explore these resources to go further.