canonical: https://jentic.com/apis/firmenwatch.ch/firmenwatch

# Firmenwatch Ch Firmenwatch API

The Firmenwatch API exposes the Swiss commercial register over REST, serving company records taken from the Zefix and LINDAS master data together with published notices from the Swiss Official Gazette of Commerce. It searches legal entities, resolves a single company by its UID, lists the officers and governing bodies on record, and streams register events as they are published. It also matches and reconciles batches of up to 500 companies, drives a resumable three-step portfolio sync, and prioritises review cases with optimistic version protection so concurrent edits do not clobber each other.

## For AI agents

Look up Swiss companies from the commercial register: resolve a UID to full details, list officers and governing bodies, follow register events, and match or reconcile batches of up to 500 entities.

## Scope

Does not handle credit scoring, financial statements, or tax filings. Use for Swiss commercial register lookups and company identity resolution only.

## Capabilities

- Search the Swiss commercial register for a legal entity by name
- Resolve a company's full register record from its UID
- List the officers and governing bodies recorded for a company
- Follow the register event stream to catch changes as they are published
- Match up to 500 company names to their UIDs in a single request
- Reconcile a portfolio of existing UIDs against the current register
- Validate and normalize a Swiss UID

## Use cases

### Agent-driven company lookup

An AI agent connected through Jentic resolves a Swiss company straight from the commercial register: given a UID it fetches the full record, lists the current officers and governing bodies, and reads the latest register events, returning a clean summary without the developer wiring the bearer auth or paging logic by hand.

Example prompt: Look up the Swiss company for a given UID, list its current officers, and summarize its most recent register events

### Portfolio reconciliation

A monitoring tool keeps a book of Swiss entities current by submitting up to 500 UIDs to the reconcile endpoint and committing a resumable portfolio sync in one atomic step, so a dropped connection mid-upload never leaves the portfolio half-updated.

Example prompt: Submit a batch of up to 500 UIDs to the reconcile endpoint and commit a portfolio sync atomically

### Register change monitoring

A compliance workflow creates a checkpoint on the event stream and then polls for new register events, matching unknown company names to UIDs as it goes, so changes of officers or legal status surface as soon as they are published in the Official Gazette of Commerce.

Example prompt: Create an event checkpoint, pull the register events published since it, and match any unknown company names to their UIDs

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/companies` | Search the Swiss commercial register |
| GET | `/companies/{uid}` | Resolve a company by its UID |
| GET | `/companies/{uid}/officers` | List a company's officers and governing bodies |
| GET | `/companies/{uid}/events` | List register events for a company |
| POST | `/companies/match` | Match up to 500 names to UIDs |
| POST | `/companies/reconcile` | Reconcile up to 500 existing UIDs |
| GET | `/events` | Stream register events |
| POST | `/uid/validate` | Validate and normalize a UID |

## Key resources

- **Companies** — Search the register, resolve a company by UID, and read its officers and events
- **Events** — Stream register events and create resumable checkpoints over them
- **Portfolios** — Begin a resumable sync, supply up to 500 rows, and commit it atomically
- **Actions** — Read prioritised review cases and update them with optimistic version protection
- **UID** — Validate and normalize Swiss UIDs and resolve a minimal public identity core

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 66 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 75 / 100
  - Developer Experience & Jentic Compatibility: 70 / 100
  - AI-Readiness & Agent Experience: 49 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 72 / 100
- **View full report:** https://jentic.com/apis/firmenwatch.ch/firmenwatch/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Firmenwatch by hand means handling its bearer-token auth, the resumable three-step portfolio sync, and optimistic version checks on review cases yourself. Through Jentic you install once, import Firmenwatch from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Firmenwatch puts the portfolio key in the URL path (`/portfolios/{sourceKey}/...`) and the review-case id in `/actions/{id}`, so a rule can pin your agent to the register read operations or to one portfolio's sync. You choose the operations it may call, so write operations like committing a sync or changing a review case are not included unless you add them.
- **Credential handling:** Your Firmenwatch token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find a Swiss company by name' or 'reconcile a portfolio of UIDs', and Jentic returns the matching Firmenwatch operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **OpenCorporates** — Global company register data rather than Switzerland-focused Zefix and SHAB records
- **Crunchbase** — Funding, investor, and private-company profiles that sit alongside statutory register data
- **Clearbit** — Firmographic and web-presence enrichment keyed off a company domain

## FAQ

### What authentication does the Firmenwatch API use?

The Firmenwatch API authenticates with a bearer token sent in the Authorization header, per its OpenAPI spec. A couple of endpoints, the public UID resolver and the health check, need no credential. Through Jentic the token is stored encrypted by your own Jentic One instance and injected at call time, so it never lands in the agent's context.

### Is there a Firmenwatch MCP server?

You don't need an MCP server to give your agent the Firmenwatch API. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls the register search, lookup, and reconcile operations on demand, without a separate server's tool definitions loaded into its context.

### Can I limit what my agent is allowed to do with the Firmenwatch API?

Yes. Write a rule that allows only the register read operations, such as searching companies and reading officers and events, so the agent can look up Swiss entities but cannot start a portfolio sync or change a review case, and every call it makes is logged.

### Can I match company names to UIDs with the Firmenwatch API?

Yes. The match endpoint takes up to 500 company names without known UIDs and returns a safe mapping to their register identities, and the reconcile endpoint checks up to 500 UIDs you already hold against the current register in one request.

### What are the rate limits for the Firmenwatch API?

The OpenAPI spec does not specify rate limits. Check the vendor documentation at https://firmenwatch.ch for the current limits and batch sizes before running large reconciliation jobs.

### How do I look up a Swiss company through Jentic?

Search Jentic for 'find a Swiss company by name', which returns the Firmenwatch search operation with its input schema, then follow up with the UID lookup to fetch the full record and officers. To run it on your own infrastructure, install Jentic One from its GitHub repo.