Strainovic IT

Zefix API: query company data from the Swiss commercial register

Zefix is Switzerland's central business name index, run by the Federal Commercial Registry Office (FCRO) within the Federal Office of Justice. Besides the search in the browser, Zefix is available as a REST interface, the "Zefix PublicREST API". With it, an application gets company name, seat, legal form, status and purpose straight from the commercial register. This guide shows access, queries and response, and when the UID register is the simpler choice.

How a Zefix query works: your application asks Zefix PublicREST with username and password for a UID or a name and receives the company data from the commercial registerYour applicationUID or companynameZefix PublicRESTSign-in withusername andpasswordCommercialregisterName, seat,legal form,status, purposeYour applicationFill in theform or checkthe customerHow a Zefix query works: your application asks Zefix PublicREST with username and password for a UID or a name and receives the company data from the commercial registerYour applicationUID or company nameZefix PublicRESTSign-in with username and passwordCommercial registerName, seat, legal form, status, purposeYour applicationFill in the form or check the customer

What the Zefix API provides

The interface lives at https://www.zefix.admin.ch/ZefixPublicREST. The endpoints are described in the Swagger interface, and machine-readable as OpenAPI at /v3/api-docs. The main endpoints:

  • GET /api/v1/company/uid/{id}: company by UID
  • POST /api/v1/company/search: search by name, legal form, seat or canton
  • GET /api/v1/sogc/bydate/{date}: one day's publications in the Swiss Official Gazette of Commerce (SOGC)
  • GET /api/v1/legalForm and GET /api/v1/community: lists of legal forms and municipalities

The data is published under "Open use" terms, with the obligation to name the source.

Step 1: request access

Queries are free but need an account. The FCRO grants access on request by email to zefix@bj.admin.ch; an email address serves as the username. Authentication uses HTTP Basic Auth, so username and password go with every request. Getting the credentials can take a few days, so ask early.

Step 2: find a company by UID

The UID goes into the path without dots or hyphen:

curl -u "user@example.ch:password" \
  https://www.zefix.admin.ch/ZefixPublicREST/api/v1/company/uid/CHE107721785

The response is a list, not a single object. If the UID is not in the commercial register, Zefix answers 404.

Step 3: find a company by name

The search expects the beginning of the company name, at least three characters, with * as a wildcard:

{
  "name": "Example*",
  "canton": "ZH",
  "activeOnly": true
}

It behaves like the exact search on the Zefix website. activeOnly hides deleted companies. Hits come in short form; the full data then comes from a query by UID.

What the response contains

  • name, uid, legalSeat (municipality of the seat) and canton
  • legalForm with the code according to eCH-0097
  • status: ACTIVE active, BEING_CANCELLED in liquidation, CANCELLED deleted, plus deletionDate
  • purpose, the purpose from the commercial register
  • address with street, house number, postcode and town
  • capitalNominal and capitalCurrency for corporations
  • sogcPub with the SOGC publications and oldNames with former names
  • cantonalExcerptWeb, the link to the cantonal commercial register excerpt

Zefix or UID register?

Zefix only knows companies with a commercial register entry. The UID register of the Federal Statistical Office knows every company with a UID, including sole proprietorships and associations without an entry, and shows the entry in the VAT register. Its public lookup needs no account.

To find out whether a UID entered in the checkout is valid and the company active, the UID register is therefore enough. Zefix pays off when purpose, capital, former names or publications are needed. How to check via the UID register is explained in the guide validate a Swiss UID number.

Pitfalls

  • UID spelling: in the path without separators (CHE107721785), on display with them (CHE-107.721.785). Normalise before the query.
  • List instead of object: even the query by UID returns a list.
  • Liquidation: BEING_CANCELLED is not deleted yet, but no longer an ordinary business partner. Your application has to decide how to handle it.
  • Credentials: username and password stay on the server. A call from the browser would show them to every visitor.
  • Caching: company data rarely changes. Keep answers for a while instead of asking again on every page view.

Ready for the shop

To validate UIDs in the WooCommerce checkout you need no code of your own: my UID check plugin validates format, check digit and status in the UID register, with no account and no key.

All guides