Skip to content

Endpoints

POST /v1/name/screening (convenience orchestration)

This is the one-call screening endpoint for partners who want the API to coordinate multiple checks in one request.

By default it runs:

  • company name assessment
  • company conflict search
  • trademark search

It can also run optional domain availability checks when explicitly enabled.

Business purpose

Use this endpoint when your integration wants one bundled response to the question:

What is the overall screening outcome for this proposed name across assessment, company conflicts, trademark signals, and optional domain checks?

This endpoint is intended for:

  • partner backends that want one call instead of orchestrating multiple upstream calls
  • intake workflows that need a broader screening bundle before handoff
  • internal systems that want one structured response with compact supporting detail

Positioning relative to assessment

  • POST /v1/name/assessment remains the lean primary decision API.
  • POST /v1/name/screening is the convenience orchestration API.
  • Use screening when you want breadth in one request.
  • Use assessment when you want the simplest decision-oriented contract and lower-latency scope.

Response handling

  • overallStatus is the primary business outcome to persist and branch on.
  • resultState tells you whether every requested check completed successfully.
  • drivers[] gives you compact machine-readable reasons that materially influenced the outcome.
  • primaryConcern gives you one strongest issue to display prominently.
  • checkStates shows which requested checks completed, failed, or were not requested.
  • executionIssues[] is only relevant when resultState=PARTIAL.
  • details contains compact per-check detail for completed checks, including risk-tier counts and truncated top matches.
  • Use code and enum fields for UI routing and localized copy lookup. message fields are English fallback/debug copy only.

Example request

curl -X POST "https://api.test.checkname.ch/v1/name/screening" \
  -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",
    "checks": {
      "ehraCompliance": { "enabled": true },
      "conflicts": { "enabled": true, "limit": 25, "minRisk": "Low" },
      "trademarks": { "enabled": true, "limit": 20, "minRisk": "Low", "niceClasses": [35, 42] },
      "domains": { "enabled": false }
    }
  }'

Example response

{
  "overallStatus": "MANUAL_REVIEW_ADVISED",
  "resultState": "COMPLETE",
  "nextAction": "ROUTE_TO_MANUAL_REVIEW",
  "drivers": [
    {
      "source": "trademarks",
      "code": "TRADEMARK_MATCHES",
      "severity": "review"
    }
  ],
  "primaryConcern": {
    "source": "trademarks",
    "code": "TRADEMARK_MATCHES",
    "severity": "review",
    "risk": "High",
    "referenceId": "600643",
    "label": "LEGIC"
  },
  "checkStates": {
    "ehraCompliance": "completed",
    "conflicts": "completed",
    "trademarks": "completed",
    "domains": "not_requested"
  },
  "executionIssues": [],
  "details": {
    "ehraCompliance": {
      "issues": [],
      "semanticFailOpen": false
    },
    "conflicts": {
      "identityMatchFound": false,
      "identityMatch": null,
      "similarMatchCount": 4,
      "matchCountsByRisk": { "high": 0, "medium": 0, "low": 4 },
      "highestRisk": "Low",
      "topMatches": [
        {
          "sourceCompanyId": "CHE178042350",
          "nameDisplay": "LEG GmbH",
          "legalSeat": "Obfelden",
          "nameNorm": "leg",
          "visualScore": 0.375,
          "phoneticMatch": false,
          "risk": "Low"
        }
      ],
      "hasMoreMatches": true
    },
    "trademarks": {
      "similarMatchCount": 13,
      "matchCountsByRisk": { "high": 1, "medium": 0, "low": 12 },
      "highestRisk": "High",
      "goodsServicesContextApplied": true,
      "topMatches": [
        {
          "sourceRecordId": "600643",
          "registrationNumber": "600643",
          "applicationNumberText": "57063/2009",
          "markText": "LEGIC",
          "markTextNorm": "legic",
          "status": "Registration published",
          "niceClasses": [9, 35, 37, 38, 42],
          "classOverlap": [35, 42],
          "relatedClassOverlap": [9],
          "visualScore": 0.44444445,
          "phoneticMatch": true,
          "matchBasis": ["class_overlap", "phonetic_match"],
          "risk": "High"
        }
      ],
      "hasMoreMatches": true
    },
    "domains": null
  },
  "traceId": "trc_screening_example"
}

GET /v1/name/screening/catalog (response code catalog)

This endpoint exposes the stable screening response contract at runtime.

Business purpose

Use this endpoint when your frontend or backend needs to know all current screening codes and enum values without manually copying them from documentation.

The catalog is intended for:

  • building German UI copy maps keyed by stable codes
  • validating that your integration handles all known screening issue and driver codes
  • refreshing partner-side routing/configuration when new non-breaking codes are introduced

Response handling

  • assessmentIssueCodes[] lists possible details.ehraCompliance.issues[] values.
  • driverCodes[] lists possible drivers[] and primaryConcern driver values.
  • message values are English fallback/debug descriptions only.
  • Use code, severity, category, source, and enum values as machine-readable integration keys.
  • See API Reference > Assessment Checks and Codes for the full human-readable tables with all catalog codes, English descriptions, example triggers, and partner handling notes.

Example request

curl -X GET "https://api.test.checkname.ch/v1/name/screening/catalog" \
  -H "X-API-Key: <your-api-key>"

Example response

{
  "assessmentIssueCodes": [
    {
      "code": "ERR_MISSING_LEGAL_FORM",
      "severity": "ERROR",
      "category": "LEGAL_FORM",
      "message": "The legal form is missing or not recognizable in the primary name."
    }
  ],
  "assessmentIssueSeverities": ["INFO", "WARNING", "ERROR"],
  "assessmentIssueCategories": ["SYNTAX", "LEGAL_FORM", "GEOGRAPHIC", "TRANSLATION", "SEMANTIC", "REGULATORY"],
  "overallStatuses": ["CLEAR_TO_FILE", "MINOR_RISKS_DETECTED", "MANUAL_REVIEW_ADVISED", "REGISTRY_REJECTION_LIKELY"],
  "resultStates": ["COMPLETE", "PARTIAL"],
  "nextActions": ["PROCEED", "PROCEED_WITH_CAUTION", "ROUTE_TO_MANUAL_REVIEW", "STOP_AND_REVIEW"],
  "driverSources": ["assessment", "conflicts", "trademarks", "domains", "execution"],
  "driverCodes": [
    {
      "code": "REQUESTED_CHECK_FAILED",
      "source": "execution",
      "defaultSeverity": "review",
      "message": "One or more requested screening checks failed to complete."
    }
  ],
  "driverSeverities": ["info", "warning", "review", "block"],
  "checkStates": ["completed", "failed", "not_requested"],
  "riskLevels": ["High", "Medium", "Low"],
  "errorCodes": ["VALIDATION_ERROR", "INVALID_REQUEST", "UNAUTHORIZED", "RATE_LIMITED", "UPSTREAM_ERROR", "UPSTREAM_TIMEOUT", "INTERNAL_ERROR"]
}

POST /v1/name/assessment (lean 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

  • Top-level overallStatus is the recommended integration signal.
  • issues[].code explains which exact rules or concerns were triggered.
  • semanticSignals provides supporting semantic evidence and context.
  • 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; send the current official family name)
  • 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 issues 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.

Sole proprietorship surname handling

When legalForm="sole_proprietorship", ownerSurname is used as the official family name for Art. 945 OR checks.

The API matches spelling with Unicode-aware normalization and casefolding, but it does not transliterate or alter the legal spelling. Umlauts and accents remain significant: ü, ä, ö, é, è, à, and similar characters are not equivalent to ue, ae, oe, e, or a. For example, Müller Bäckerei can satisfy ownerSurname="Müller", but Mueller Bäckerei does not. Elektro Cisco does not satisfy ownerSurname="Francisco". Multi-part and hyphenated official family names must appear as submitted.

Relevant issue codes:

  • ERR_SOLE_PROP_SURNAME_MISSING: the official family name is missing, shortened, transliterated, or otherwise altered in the proposed name.
  • WARN_SOLE_PROP_OWNER_SURNAME_AMBIGUOUS: another surname-like element appears and the proprietor is not clearly identified, such as Restaurant Schönenberger, Mathys instead of Restaurant Schönenberger, Inhaberin Mathys.
  • ERR_INVALID_SOLE_PROP_SUFFIX: the name implies a company/partnership relationship or contains an invalid legal-form indicator, such as Faller Finance Partnership, AG Muster, or A.G. Muster.

Response handling

  • Use top-level overallStatus as the business outcome.
  • Use issues[] for machine-readable policy triggers (code, severity, category).
  • Treat issues[].message as English fallback/debug copy, not as the primary localized UI copy.
  • Read semanticSignals as explainability context (mostly relevant in full mode).
  • Use semanticFailOpen to detect when semantic execution was requested but unavailable.
  • See API Reference > Assessment Checks and Codes for the complete check/code matrix.

Decision mapping example

switch (response.overallStatus) {
  case "CLEAR_TO_FILE":
    // Continue automatically
    break;
  case "MINOR_RISKS_DETECTED":
    // Continue with warning UI
    break;
  case "MANUAL_REVIEW_ADVISED":
    // Route to manual review
    break;
  case "REGISTRY_REJECTION_LIKELY":
    // Block or escalate before filing
    break;
}

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

{
  "companyName": "Legiqo GmbH",
  "overallStatus": "CLEAR_TO_FILE",
  "riskProfileApplied": "balanced",
  "issues": [],
  "semanticSignals": {
    "impliedActivities": [],
    "isPurelyDescriptive": false,
    "containsGeographicTerm": false
  },
  "semanticFailOpen": false,
  "traceId": "trc_f8bfb7db8e4848fabc0b2b2dfeb7fe48"
}

Example response (semanticFailOpen=true)

{
  "companyName": "Kaufhaus AG",
  "overallStatus": "MANUAL_REVIEW_ADVISED",
  "riskProfileApplied": "balanced",
  "issues": [
    {
      "code": "WARN_PURELY_DESCRIPTIVE",
      "severity": "WARNING",
      "category": "SEMANTIC",
      "message": "The name appears purely descriptive and may lack distinctiveness."
    }
  ],
  "semanticSignals": null,
  "semanticFailOpen": true,
  "traceId": "trc_88fe2ab77c67438e8c7a4ca886ab1652"
}

When semanticFailOpen=true, the request still completed successfully. Apply your own policy for whether that case can proceed with warning or requires manual review.

Important HTTP semantics

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

POST /v1/conflicts/search

Finds already registered Swiss company names that are identical or similar to the proposed name, using identity, visual similarity, phonetics, and subset logic.

Business purpose

Use this endpoint when your partner application needs to identify already 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 already registered identical or similar names

What the endpoint returns

The response is not a registry approval/rejection decision. Instead, it returns already registered 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
  • registered company 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 already registered company names are identical or similar to this proposed name?"

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 showing why a registered name matched
  • Matched registered company entities for follow-up review

Decision mapping example

if (response.identityMatch) {
  // Treat as immediate escalation or block
} else if (response.similarMatches.some((match) => match.risk === "High")) {
  // Show strong warning or require analyst review
} else {
  // Continue with advisory context
}

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"
    }
  ]
}

Example response with identityMatch

{
  "input": {
    "name": "Alpen Data AG",
    "nameNorm": "alpen data",
    "nameCore": "alpen data",
    "phoneticPrimary": "ALPN",
    "phoneticAlt": "ALPN"
  },
  "registrable": false,
  "identityMatch": {
    "sourceCompanyId": "CHE123456789",
    "nameDisplay": "Alpen Data AG",
    "legalSeat": "Zurich",
    "nameNorm": "alpen data",
    "risk": "Critical"
  },
  "similarMatches": []
}

POST /v1/trademarks/search

Screens for potentially similar registered trademarks in the ingested IGE dataset using deterministic text, phonetic, and Nice-class-aware matching.

Business purpose

Use this endpoint when your partner workflow needs an additional trademark-oriented screening signal beyond company-name checks.

It is especially useful for:

  • brand-precheck workflows before filing or legal handoff
  • analyst review screens that compare a proposed sign against registered marks
  • intake flows where partners want an early trademark-warning layer
  • case-management tools that store structured similarity reasons for later review

What the endpoint returns

The response is not a legal clearance opinion. Instead, it returns potentially similar trademark records with deterministic explainability fields that help reviewers assess whether a trademark conflict may deserve follow-up review.

Typical response value includes:

  • trademark candidates ordered by computed risk
  • text and phonetic similarity signals
  • Nice-class overlap context when niceClasses are provided
  • matchBasis[] explanations showing why a candidate was surfaced

How it differs from the other search endpoints

  • POST /v1/name/assessment answers: "How should our workflow treat this proposed company name?"
  • POST /v1/conflicts/search answers: "Which already registered Swiss company names are identical or similar to this proposed company name?"
  • POST /v1/trademarks/search answers: "Which registered trademarks may be similar enough to this proposed mark to warrant review?"

Typical use

  • Run after a proposed brand or sign is known.
  • Provide niceClasses when you know the intended goods/services scope.
  • Show top trademark candidates grouped by risk for legal or operator review.

Key response concepts

  • goodsServicesBasis tells you whether Nice-class context was used
  • classOverlap shows direct Nice-class intersection
  • relatedClassOverlap shows curated nearby Nice-class matches
  • matchBasis[] explains why a mark was returned
  • risk provides the top-level integration signal for ordering and routing

Decision mapping example

const highRiskTrademark = response.similarMatches.some((match) => match.risk === "High");

if (highRiskTrademark) {
  // Escalate to legal or trademark review
} else if (response.similarMatches.length > 0) {
  // Continue with warning and analyst visibility
} else {
  // No relevant trademark signal returned
}

Request fields

  • query (string, required)
  • limit (integer, optional, default 25, max 100)
  • minRisk (Low | Medium | High, default Low)
  • niceClasses (array of integers 1-45, optional; improves goods/services weighting)

Example request

curl -X POST "https://api.test.checkname.ch/v1/trademarks/search" \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Mueller Soehne",
    "limit": 20,
    "minRisk": "Low",
    "niceClasses": [35, 42]
  }'

Example response

{
  "input": {
    "query": "Mueller Soehne",
    "queryNorm": "mueller soehne",
    "queryCore": "mueller soehne",
    "phoneticPrimary": "MLRS",
    "phoneticAlt": "MLRS",
    "niceClasses": [35, 42]
  },
  "goodsServicesBasis": "nice_classes",
  "similarMatches": [
    {
      "sourceRecordId": "TM-REG-1",
      "registrationNumber": "TM-REG-1",
      "applicationNumberText": null,
      "markText": "Mueller Soehne",
      "markTextNorm": "mueller soehne",
      "status": "ACTIVE",
      "niceClasses": [35, 42],
      "classOverlap": [35, 42],
      "relatedClassOverlap": [],
      "visualScore": 1.0,
      "phoneticMatch": true,
      "matchBasis": [
        "exact_text",
        "class_overlap"
      ],
      "risk": "High"
    }
  ]
}

Important HTTP semantics

  • HTTP 200 means successful trademark search execution, even if no matches are returned.
  • Empty similarMatches means no candidates met the current matching and minRisk threshold.

Deprecated eligibility endpoints

The following endpoints are deprecated:

  • POST /v1/name/eligibility
  • POST /v2/name/eligibility
  • POST /v3/name/eligibility

They are legacy eligibility-style APIs and have been replaced for partner integrations by POST /v1/name/assessment.

Business context

These endpoints reflect older partner integration models where clients consumed rule-centric or eligibility-centric results instead of the newer assessment abstraction.

Why it is deprecated

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

Migration note

  • New integrations should use POST /v1/name/assessment.
  • Existing integrations should migrate off POST /v1/name/eligibility, POST /v2/name/eligibility, and POST /v3/name/eligibility.
  • Keep eligibility only while migrating existing clients.

Legacy example request (POST /v1/name/eligibility)

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"
  }'

Legacy example response (POST /v1/name/eligibility)

{
  "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
  }
}