Skip to content

Endpoints

POST /v1/name/assessment (primary)

Legiqo's main partner endpoint for name decisioning. It combines:

  • deterministic policy checks
  • semantic extraction (when checkLevel=full)
  • profile-based risk mapping into a final business outcome

Business purpose

Use this endpoint when you need one integrated answer to the question:

Can this proposed company name move forward in our workflow, and if not, why?

This endpoint is intended for:

  • frontends that need an immediate approval/warn/review/block signal
  • operations tools that route cases to manual review
  • internal systems that must store structured risk reasons
  • assisted filing flows that need a single primary decision API

What the endpoint evaluates

Depending on the request, the endpoint can evaluate:

  • naming syntax and character rules
  • legal-form consistency
  • geographic wording and seat consistency
  • translation consistency across language variants
  • descriptive or potentially misleading wording
  • regulated/restricted terminology
  • implied activity signals from semantic analysis

What the response means in practice

  • assessment.overallStatus is the recommended top-level integration signal.
  • flags[] explains which exact rules or concerns were triggered.
  • semanticContext provides supporting context for explainability and auditability.
  • metadata.semanticFailOpen=true means the request completed, but semantic analysis could not be used and your manual-review policy may need to apply.

Request fields

  • companyName (string, required)
  • legalForm (enum, required)
  • activityScope (string, optional)
  • language (de | fr | it | en, required)
  • ownerSurname (string, optional; required for sole proprietorship checks)
  • legalSeat (string, optional; improves geographic consistency checks)
  • languageVariants (array, optional; multilingual consistency context)
  • checkLevel (basic | full, default full)
  • riskProfile (balanced | conservative | relaxed, default balanced; controls how triggered flags are mapped to final severity)

Choosing riskProfile

  • balanced is the default and best starting point for most production integrations.
  • conservative is stricter and escalates borderline distinctiveness concerns sooner.
  • relaxed is more permissive for intake or exploratory flows where you still want signal, but fewer cases routed into hard-stop outcomes.
  • riskProfile affects severity mapping and final status, not which checks are executed.
  • See API Reference > Assessment Checks and Codes for the exact current profile differences.

Response handling

  • Use assessment.overallStatus as the top-level business outcome.
  • Use flags[] for machine-readable policy triggers (code, severity, category).
  • Read semanticContext as explainability context (mostly relevant in full mode).
  • Use metadata.semanticFailOpen to detect when semantic execution was requested but unavailable.
  • See API Reference > Assessment Checks and Codes for the complete check/code matrix.

Example request

curl -X POST "https://api.test.checkname.ch/v1/name/assessment" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Legiqo GmbH",
    "legalForm": "limited_liability",
    "activityScope": "Development of software",
    "language": "en",
    "ownerSurname": null,
    "legalSeat": "Zurich",
    "languageVariants": [],
    "checkLevel": "full",
    "riskProfile": "balanced"
  }'

Example response

{
  "assessment": {
    "companyName": "Legiqo GmbH",
    "overallStatus": "CLEAR_TO_FILE",
    "clientProfileApplied": "balanced"
  },
  "flags": [],
  "semanticContext": {
    "impliedActivities": [],
    "isPurelyDescriptive": false,
    "containsGeographicTerm": false
  },
  "metadata": {
    "processingTimeMs": 112,
    "semanticFailOpen": false,
    "traceId": "trc_f8bfb7db8e4848fabc0b2b2dfeb7fe48"
  }
}

Important HTTP semantics

  • HTTP 200 means successful assessment execution, not automatic approval.
  • Final decision should be derived from assessment.overallStatus and flags.

POST /v1/conflicts/search

Searches for potentially conflicting Swiss company names using identity, visual similarity, phonetics, and subset logic.

Business purpose

Use this endpoint when your partner application or review team needs evidence about existing registered company names that may conflict with the proposed name.

It is especially useful for:

  • analyst review screens
  • operator workflows that need to inspect matching entities
  • escalation flows after an assessment result raises concern
  • customer-facing flows that want to show "similar existing names" context

What the endpoint returns

The response is not a registry approval/rejection decision. Instead, it returns candidate company names with conflict signals that help assess confusion risk.

Typical response value includes:

  • likely conflict matches grouped by risk
  • explainability fields showing why a match was returned
  • registry entities that a reviewer can inspect further

How it differs from assessment

  • POST /v1/name/assessment answers: "What should we do with this proposed name?"
  • POST /v1/conflicts/search answers: "Which registered names look potentially problematic, and why?"

Typical use

  • Run after a user proposes a company name.
  • Show potential conflicts grouped by risk level.

Key response concepts

  • Risk level classification (for decisioning)
  • Similarity signals for explainability
  • Matched registry entities for review

Example request

curl -X POST "https://api.test.checkname.ch/v1/conflicts/search" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Müller & Söhne AG",
    "limit": 25,
    "minRisk": "Low"
  }'

Example response

{
  "input": {
    "name": "Müller & Söhne AG",
    "nameNorm": "mueller soehne",
    "nameCore": "mueller soehne",
    "phoneticPrimary": "MLRS",
    "phoneticAlt": "MLRS"
  },
  "registrable": true,
  "identityMatch": null,
  "similarMatches": [
    {
      "sourceCompanyId": "CHE101835433",
      "nameDisplay": "Mueller und Soehne GmbH",
      "legalSeat": "Zürich",
      "nameNorm": "mueller soehne",
      "visualScore": 0.85,
      "phoneticMatch": true,
      "risk": "High"
    }
  ]
}

POST /v1/name/eligibility (deprecated)

Evaluates legal and structural naming rules for Swiss company names.

Business context

This endpoint reflects an older partner integration model where clients consumed a more rule-centric result instead of the newer assessment abstraction.

Why it is deprecated

It does not provide the same decision-oriented response model as POST /v1/name/assessment, and it should only be retained for migration compatibility.

Migration note

  • New integrations should use POST /v1/name/assessment.
  • Keep eligibility only while migrating existing clients.

Example request

curl -X POST "https://api.test.checkname.ch/v1/name/eligibility" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "companyName": "Legiqo",
    "legalForm": "limited_liability",
    "activityScope": "Development of software",
    "language": "en",
    "ownerFullName": null,
    "checkLevel": "full"
  }'

Example response

{
  "input": {
    "companyName": "Legiqo",
    "legalForm": "limited_liability",
    "activityScope": "Development of software",
    "language": "en",
    "ownerFullName": null
  },
  "overallStatus": "COMPLIANT",
  "issues": [],
  "registrableNames": {
    "de": "Legiqo GmbH",
    "fr": "Legiqo Sàrl",
    "it": "Legiqo Sagl",
    "en": "Legiqo LLC"
  },
  "metadata": {
    "processingTimeMs": 150
  }
}