n8n-nodes-zefix

Read the Swiss commercial register from n8n.

Zefix is the federal index of the commercial
register: it holds the current entry for every company in Switzerland. This node
looks a company up by UID or EHRA ID, and searches the register by name.

Built and maintained by Prospex, a Swiss B2B sales
intelligence platform.

Full documentation:
n8n-nodes-zefix.readthedocs.io.

Installation

In n8n: Settings → Community nodes → Install, then n8n-nodes-zefix.

Self-hosted, from the command line:

npm install n8n-nodes-zefix

Operations

Node	Operation	Reads
Zefix	Company → Lookup	one register entry, by UID or EHRA ID
Zefix	Company → Search	the register, by name

Both operations need credentials: every Zefix PublicREST endpoint refuses an
unauthenticated call.

Credentials

Accounts are issued by the Federal Office of Justice: write to
zefix@bj.admin.ch and say what you plan to use the API for. There is no
self-service signup and no key in a dashboard.

Once you have the username and password, add them in n8n under Credentials →
Zefix API. The credential test calls GET /legalForm, so a wrong password
fails in the dialog itself.

The Zefix REST API guide documents
all ten endpoints and the two UID formats they disagree about.

Compatibility

Requires Node.js 20.15 or newer and an n8n instance with community nodes
enabled. The package targets community node API version 1.

Every request goes through n8n's own HTTP helpers, so the package ships no
runtime dependencies.

Usage

Company → Lookup

Give it a UID or an EHRA ID. All three UID forms are accepted:

CHE-123.456.789
CHE123456789
123456789

The node emits the dotted form for display and sends the compact form to the
API, which is the only one /company/uid/{uid} matches. A UID that is not in
the register returns an empty item, so a workflow can branch on it, and the node
attaches a hint saying so. Zefix covers the commercial register alone, while
uid.admin.ch covers every UID unit, so a UID issued
for VAT alone, an association or a public body is valid there and empty here.
CHE-116.320.238, the VAT group of Banque Cantonale Vaudoise, is one: the bank
itself is CHE-105.934.376. A malformed UID is rejected before any request goes
out. Checking a Swiss
company covers where each
format shows up and what the check digit does.

Output:

Field	Notes
name, uid, uidCompact, ehraid, chid	identifiers. uid is the dotted form, the same form n8n-nodes-shab emits.
canton, legalSeat, legalSeatId	registered office
legalFormId, legalFormUid, legalForm	the internal ID, the four-character eCH-0097 code, and the localised names
status	ACTIVE, CANCELLED or BEING_CANCELLED
purpose	the statutory purpose, in the language of the cantonal register it is entered in
capitalNominal, capitalCurrency	nominal capital as a string, and its currency
deletionDate, sogcDate	dates
address	street, house number, PO box, ZIP, town
oldNames, translation	former names, and registered translations
headOffices, furtherHeadOffices, branchOffices	company relations
hasTakenOver, wasTakenOverBy, auditCompanies	company relations
cantonalExcerptWeb	link to the cantonal extract
zefixDetailWeb	Zefix detail pages, one per language

cantonalExcerptWeb comes from the API. The hosts are per-canton
(zg.chregister.ch, rc.zh.ch, prestations.vd.ch), so use the returned link
and do not build one.

Company → Search

A name of at least 3 characters, with * as a wildcard. Optional: canton, legal
form (a dropdown fed by /legalForm), and a switch to drop struck companies.
Each row is the Zefix search record, with uid in the dotted form and
uidCompact alongside it, in the same form Lookup emits.

Canton, Legal Seat ID and Registry of Commerce ID are mutually exclusive in the
API. Setting two raises an error naming both, before the request is sent. The
search endpoint returns everything it has in one response, so the limit is
applied by the node.

Example workflow

examples/hubspot-enrich-from-uid.json,
importable as it is: read companies out of HubSpot, look each UID up in Zefix,
write the name, address and purpose back.

Access and terms

Zefix PublicREST needs the Basic credentials described above. The node paces it
at one request every 0.5 seconds and retries a 429 or a 5xx three times. A run
of failed retries throws, so an empty result always means the company is absent
from the register. Its User-Agent carries this repository's URL.

The register data is also published as linked data through LINDAS, under terms
the Federal Office of Justice states on
the Zefix site. Read
those before redistributing bulk extracts.

Watching the whole register

Zefix holds the current entry, not its history, so it cannot say what changed.
n8n-nodes-shab reads the
gazette and triggers on a UID list.
Prospex watches the whole register and joins it to hiring,
funding and web signals, then says which of those changes is worth a call.

Resources

• n8n community nodes documentation
• Zefix and the Zefix REST API guide
• n8n-nodes-shab, the gazette side

The register is also reachable outside n8n:

Package	Does
zefix-parser	the register entry: LINDAS SPARQL, PublicREST, UID validation
shab-parser	the gazette: discovery, fetch, parse, eleven-type event classification
swissco	the same register from a command line, plus simap, FINMA, GLEIF and ARAMIS

Development

npm install
npm run dev     # starts n8n with the node linked
npm run lint
npm run build
npm test

License

MIT