VynCo 3.2.1

VynCo .NET SDK

.NET SDK for the VynCo Swiss Corporate Intelligence API. Access 500,000+ Swiss companies from the commercial register with change tracking, sanctions screening, AI-powered risk analysis, network graphs, watchlists, webhooks, and bulk data exports.

Installation

dotnet add package VynCo

Targets: .NET Standard 2.0 (.NET Framework 4.6.1+, .NET Core 2.0+) and .NET 10.0.

Quick Start

using VynCo;
using VynCo.Models;

using var client = new VynCoClient("vc_live_your_api_key");

// List companies with filtering
var result = await client.Companies.ListAsync(
    new CompanyListParams { Search = "Novartis", Canton = "BS" });
Console.WriteLine($"Found {result.Total} companies");

// Get a single company
var company = await client.Companies.GetAsync("CHE-105.805.080");
Console.WriteLine($"{company.Name}: {company.LegalForm}");

// Full company with persons and changes
var full = await client.Companies.GetFullAsync("CHE-105.805.080");
Console.WriteLine($"Persons: {full.Persons.Count}, Changes: {full.RecentChanges.Count}");

// Sanctions screening
var screening = await client.Screening.ScreenAsync(
    new ScreeningRequest { Name = "Suspicious Corp" });
Console.WriteLine($"Risk: {screening.RiskLevel} ({screening.HitCount} hits)");

// AI risk score
var risk = await client.Ai.RiskScoreAsync(
    new RiskScoreRequest { Uid = "CHE-105.805.080" });
Console.WriteLine($"Risk score: {risk.OverallScore}/100 ({risk.RiskLevel})");

// Credit balance
var credits = await client.Credits.BalanceAsync();
Console.WriteLine($"Credits remaining: {credits.Balance}");

API Coverage

20 resource modules covering 100+ endpoints:

New in v3.1

• Historical timeline — Companies.TimelineAsync(uid, params?) and AI narrative via TimelineSummaryAsync(...)
• Similar companies — Companies.SimilarAsync(uid, { Limit }) scored on industry, canton, capital, legal form, auditor tier
• UBO resolution — Companies.UboAsync(uid) walks the ownership chain and identifies natural persons
• Ownership trace — Ownership.TraceAsync(uid, { MaxDepth }) exposes the full chain with circular-ownership detection
• Media with sentiment — Companies.MediaAsync(uid, { Sentiment }) filtered by positive/neutral/negative
• Batch operations — Screening.BatchAsync(...) (up to 100) and Ai.RiskScoreBatchAsync(...) (up to 50)
• Market analytics — Analytics.FlowsAsync(...), Analytics.MigrationsAsync(...), Analytics.BenchmarkAsync(uid, ...)
• Person network — Persons.NetworkAsync(id) for person-centric investigations with co-directors
• Saved alerts — persistent saved queries with optional webhook delivery
• Pagination on board members — new Persons.BoardMembersPagedAsync(uid, { Page, PageSize }) (max 500)
• Typed hierarchy — HierarchyResponse now uses HierarchyEntity (was JsonElement)
• Enriched watchlists — WatchlistCompaniesResponse.Companies includes name/status/canton
• ExportCsvAsync — new canonical name (ExportExcelAsync kept as [Obsolete] alias)

Response Metadata

Every API response includes header metadata for credit tracking and rate limiting:

await client.Companies.GetAsync("CHE-105.805.080");

var h = client.LastResponseHeaders;
Console.WriteLine($"Request ID:          {h?.RequestId}");          // X-Request-Id
Console.WriteLine($"Credits used:        {h?.CreditsUsed}");        // X-Credits-Used
Console.WriteLine($"Credits remaining:   {h?.CreditsRemaining}");   // X-Credits-Remaining
Console.WriteLine($"Rate limit:          {h?.RateLimitLimit}");     // X-RateLimit-Limit
Console.WriteLine($"Rate limit remaining:{h?.RateLimitRemaining}"); // X-RateLimit-Remaining
Console.WriteLine($"Rate limit reset:    {h?.RateLimitReset}");     // X-RateLimit-Reset
Console.WriteLine($"Data source:         {h?.DataSource}");         // X-Data-Source

Configuration

using var client = new VynCoClient(
    apiKey: "vc_live_your_api_key",
    baseUrl: "https://vynco.ch/api",    // default
    maxRetries: 2,                       // default; retries on 429 and 5xx
    timeout: TimeSpan.FromSeconds(30)    // default
);

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 header, falls back to X-RateLimit-Reset, and caps retry delay at 60 seconds.

Error Handling

All API errors are mapped to typed exceptions with RFC 7807 Problem Details:

try
{
    var company = await client.Companies.GetAsync("CHE-000.000.000");
}
catch (AuthenticationException) { Console.WriteLine("Invalid API key"); }
catch (InsufficientCreditsException) { Console.WriteLine("Top up credits"); }
catch (ForbiddenException) { Console.WriteLine("Insufficient permissions"); }
catch (NotFoundException ex) { Console.WriteLine($"Not found: {ex.Body?.Detail}"); }
catch (ValidationException ex) { Console.WriteLine($"Bad request: {ex.Body?.Detail}"); }
catch (ConflictException) { Console.WriteLine("Resource conflict"); }
catch (RateLimitException) { Console.WriteLine("Rate limited, retry later"); }
catch (ServerException) { Console.WriteLine("Server error"); }
catch (VynCoException ex) { Console.WriteLine($"Error: {ex.Message}"); }

Error bodies follow RFC 7807 Problem Details with Type, Title, Status, Detail, and Instance fields.

Pagination

var page = await client.Companies.ListAsync(
    new CompanyListParams { Canton = "ZH", Page = 1, PageSize = 50 });

foreach (var company in page.Items)
    Console.WriteLine($"{company.Uid}: {company.Name}");

Watchlists

// Create a watchlist
var watchlist = await client.Watchlists.CreateAsync(
    new CreateWatchlistRequest { Name = "Portfolio", Description = "Tracked companies" });

// Add companies
await client.Watchlists.AddCompaniesAsync(watchlist.Id,
    new AddCompaniesRequest { Uids = new List<string> { "CHE-105.805.080", "CHE-109.340.740" } });

// Get events
var events = await client.Watchlists.EventsAsync(watchlist.Id, limit: 20);

Analytics

// Clustering analysis
var clusters = await client.Analytics.ClusterAsync(
    new ClusterRequest { Algorithm = "kmeans", K = 5 });

// Canton distribution
var cantons = await client.Analytics.CantonsAsync();

// Audit candidates
var candidates = await client.Analytics.CandidatesAsync(
    new CandidateParams { Canton = "ZH", SortBy = "shareCapital" });

License

Apache-2.0