Skip to content

Name Assessment Integration Guide

Use POST /v1/name/assessment as the default endpoint in your partner integration.

For most B2B implementations, this is the primary API call that turns a proposed Swiss company name into an operational decision signal.

Regulatory and methodological basis

The POST /v1/name/assessment endpoint is grounded in Swiss company-name formation principles and EHRA-oriented review logic.

In particular, the assessment rules are aligned with the official Federal Office of Justice guidance document Anleitung und Weisung an die Handelsregisterbehörden für die Bildung und Prüfung von Firmen und Namen (1 April 2021).

Important:

  • the endpoint is designed to reflect the published rule framework used for Swiss company-name review
  • it helps partners apply those rules consistently at scale in their own workflows
  • it does not replace the formal review performed by the competent commercial registry authorities

What the endpoint does

  • Runs deterministic checks against name/legal form/geographic constraints.
  • Optionally runs semantic extraction when checkLevel=full.
  • Maps triggered rule codes through a selected risk profile (balanced, conservative, relaxed).
  • Returns final status in overallStatus plus machine-readable issues.

Decision model

Treat overallStatus as your primary business signal:

  • CLEAR_TO_FILE: no blocking findings in current profile
  • MINOR_RISKS_DETECTED: low-severity findings, show warnings
  • MANUAL_REVIEW_ADVISED: requires legal/compliance/manual review
  • REGISTRY_REJECTION_LIKELY: high rejection risk, block or escalate
  1. Parse overallStatus first.
  2. Map issues[].code to deterministic UI messages/workflow actions.
  3. Display issues[].message to operators as supporting rationale.
  4. Store traceId as the canonical support identifier and, if useful, log the mirrored X-Trace-Id response header.
  5. If semanticFailOpen=true, route to manual review policy.

Request design tips

  • Keep companyName consistent with legalForm.
  • Provide legalSeat whenever available to improve geographic checks.
  • For sole proprietorship checks, send ownerSurname as the owner's current official family name.
  • Use languageVariants when multilingual names are expected in registry usage.

Sole proprietorship names

For legalForm="sole_proprietorship", the owner's family name is legally material under Art. 945 OR.

Use ownerSurname for the official family name, not a display name or transliteration. The check uses Unicode-aware normalization and casefolding, so case differences are ignored but diacritics are preserved. In practice, ü, ä, ö, é, è, à, and similar characters are not treated as ue, ae, oe, e, or a.

  • Müller Bäckerei with ownerSurname="Müller" can pass.
  • Mueller Bäckerei with ownerSurname="Müller" is flagged because the submitted spelling does not match the official spelling.
  • Épiney Atelier with ownerSurname="Épiney" can pass; Epiney Atelier with ownerSurname="Épiney" is treated as a spelling change.
  • Elektro Cisco with ownerSurname="Francisco" is flagged because the family name is shortened or altered.
  • Alvarez Diaz Gonzales Rodriguez Consulting can pass with ownerSurname="Alvarez Diaz Gonzales Rodriguez"; Alvarez Consulting is not enough.
  • Muster-Hugi Beratung and Muster Hugi Beratung are different legal-name spellings. Submit the spelling that matches the official family name.
  • Faller Finance Partnership, Materazzi Building Company, AG Muster, and A.G. Muster are not suitable sole-proprietorship names because they imply a company, partnership, or incorrect legal form.

If the proposed name contains another apparent family name, make the proprietor clear, for example Restaurant Schönenberger, Inhaberin Mathys. Without clarification, the API can return WARN_SOLE_PROP_OWNER_SURNAME_AMBIGUOUS and route the assessment to manual review.