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.

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 assessment.overallStatus plus machine-readable flags.

Decision model

Treat assessment.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 assessment.overallStatus first.
  2. Map flags[].code to deterministic UI messages/workflow actions.
  3. Display flags[].message to operators as supporting rationale.
  4. Store metadata.traceId and response header X-Trace-Id.
  5. If metadata.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.
  • Use languageVariants when multilingual names are expected in registry usage.