Assessment Checks and Codes¶

This page gives a complete overview of checks that can affect POST /v1/name/assessment, and the related machine-readable flag/error codes.

How to use this page¶

Use assessment.overallStatus as the top-level decision signal.
Use flags[].code as deterministic workflow triggers.
Use flags[].severity with your chosen riskProfile (balanced, conservative, relaxed).
Use endpoint error codes (HTTP + error.code) for retry and client error handling.

What `riskProfile` does¶

riskProfile does not change which checks run.

It changes how triggered flags are mapped into severity levels, which then drives the final assessment.overallStatus.

In other words:

the rule engine still detects the same underlying issue
the selected profile decides whether that issue should be treated as INFO, WARNING, or ERROR
the highest mapped severity becomes the final status returned to the client

This matters because the same proposed company name can lead to a different top-level outcome depending on the profile you choose.

Assessment outcomes¶

assessment.overallStatus is derived from the highest mapped severity among all triggered flags:

Highest mapped severity	`assessment.overallStatus`
`ERROR`	`REGISTRY_REJECTION_LIKELY`
`WARNING`	`MANUAL_REVIEW_ADVISED`
`INFO`	`MINOR_RISKS_DETECTED`
no flags	`CLEAR_TO_FILE`

1) Syntax and character checks¶

Check	Trigger condition (summary)	Flag code	Category
Invalid/prohibited symbols	Unsupported/prohibited symbols in company name	`ERR_PROHIBITED_SYMBOL`	`SYNTAX`
Invalid punctuation	Prohibited punctuation structure	`ERR_INVALID_PUNCTUATION`	`SYNTAX`
Excessive whitespace	Multiple spaces between tokens	`ERR_MULTIPLE_SPACES`	`SYNTAX`
Non-Latin script	Non-Latin alphabetic characters detected	`ERR_NON_LATIN_CHARACTERS`	`SYNTAX`

2) Legal form checks¶

Check	Trigger condition (summary)	Flag code	Category
Missing/incompatible legal form	Legal form missing or not recognizable in primary name	`ERR_MISSING_LEGAL_FORM`	`LEGAL_FORM`
Multiple legal forms	More than one legal form in primary name	`ERR_MULTIPLE_LEGAL_FORMS`	`LEGAL_FORM`
Hidden legal-form token	Legal form token embedded in another word	`ERR_HIDDEN_LEGAL_FORM`	`LEGAL_FORM`
English legal form in primary name	English legal form without Swiss-form context	`ERR_ENGLISH_LEGAL_FORM_PRIMARY`	`LEGAL_FORM`
Sole proprietorship suffix conflict	Corporate/partnership suffix in sole proprietorship context	`ERR_INVALID_SOLE_PROP_SUFFIX`	`LEGAL_FORM`

3) Geographic checks¶

Check	Trigger condition (summary)	Flag code	Category
Standalone geography	Core name is only a geographic designation	`ERR_STANDALONE_GEOGRAPHY`	`GEOGRAPHIC`
Seat mismatch	Name geography conflicts with provided `legalSeat`	`WARN_SEAT_MISMATCH`	`GEOGRAPHIC`
Origin/provenance indication	Potentially regulated origin indication wording	`WARN_ORIGIN_INDICATION`	`GEOGRAPHIC`

4) Translation checks (with semantic context)¶

These checks require semantic extraction (checkLevel=full).

Check	Trigger condition (summary)	Flag code	Category
Translation mismatch	`languageVariants` not semantically aligned to primary name	`ERR_TRANSLATION_MISMATCH`	`TRANSLATION`
Untranslatable element altered	Translation changes untranslatable elements	`ERR_TRANSLATION_UNTRANSLATABLE`	`TRANSLATION`

5) Semantic distinctiveness and purpose checks (`checkLevel=full`)¶

Check	Trigger condition (summary)	Flag code	Category
Purely descriptive name	Name appears non-distinctive/descriptive	`WARN_PURELY_DESCRIPTIVE`	`SEMANTIC`
Deceptive purpose signal	Implied activities diverge from `activityScope`	`WARN_DECEPTIVE_PURPOSE`	`SEMANTIC`

6) Regulatory/restricted-term checks¶

Some checks can be triggered deterministically and/or semantically (when checkLevel=full).

Check	Trigger condition (summary)	Flag code	Category
Regulated financial terms	Banking/investment wording requiring FINMA context	`WARN_FINMA_LICENSE_REQUIRED`	`REGULATORY`
Implied investment/banking activity	Semantic implication of regulated financial activity	`WARN_IMPLIED_INVESTMENT_OR_BANKING_ACTIVITY`	`REGULATORY`
Gambling terms	Gambling-related terms/signals	`WARN_GAMBLING_TERMS_GSG`	`REGULATORY`
Healthcare/pharmacy terms	Pharmacy-related wording	`WARN_HEALTH_APOTHEKE_HMG`	`REGULATORY`
Healthcare claim signal	Semantic health-claim implication	`WARN_HEALTH_CLAIM_HMG`	`REGULATORY`
Higher-education terms	University/HE wording requiring HFKG context	`WARN_HFKG_ACCREDITATION_REQUIRED`	`REGULATORY`
Official/state designation	Official designation terms detected	`WARN_OFFICIAL_DESIGNATION`	`REGULATORY`
Protected international organization (strict)	Protected org names/sigils detected	`ERR_PROTECTED_INTL_ORG_STRICT`	`REGULATORY`
Protected international organization (ambiguous)	Ambiguous protected sigil reference	`WARN_PROTECTED_INTL_ORG_AMBIGUOUS`	`REGULATORY`

Risk profile differences¶

The same flag code can map to different severities by riskProfile.

Available profiles¶

Profile	Intended use	Practical effect
`balanced`	Default profile for most partner integrations	A middle-ground setup intended for normal production decisioning
`conservative`	Stricter filing or compliance workflows	Escalates borderline distinctiveness concerns more aggressively
`relaxed`	Early-stage intake, exploratory UX, or lower-friction screening	Downgrades some borderline concerns so more cases can continue with warning context

Current behavior in the API¶

At the moment, only one listed flag changes severity between profiles:

Flag code	Meaning (summary)	`balanced`	`conservative`	`relaxed`
`WARN_PURELY_DESCRIPTIVE`	The proposed name appears insufficiently distinctive or too descriptive	`WARNING`	`ERROR`	`INFO`

This means:

with balanced, a purely descriptive name typically leads to manual review
with conservative, the same issue is treated as registry-rejection risk
with relaxed, the same issue becomes an informational concern rather than a review/blocking signal

Outcome impact¶

Because final status is based on the highest mapped severity, the same flag can produce different outcomes:

Highest mapped severity	Resulting `assessment.overallStatus`
`ERROR`	`REGISTRY_REJECTION_LIKELY`
`WARNING`	`MANUAL_REVIEW_ADVISED`
`INFO`	`MINOR_RISKS_DETECTED`

For example, if the only triggered flag is WARN_PURELY_DESCRIPTIVE:

`riskProfile`	Mapped severity	Resulting status
`balanced`	`WARNING`	`MANUAL_REVIEW_ADVISED`
`conservative`	`ERROR`	`REGISTRY_REJECTION_LIKELY`
`relaxed`	`INFO`	`MINOR_RISKS_DETECTED`

All other listed flags currently use the same severity across profiles.

Endpoint-level error codes (`POST /v1/name/assessment`)¶

These are transport/request errors (separate from flags[] in successful 200 responses):

HTTP status	`error.code`	Meaning
`400`	`INVALID_REQUEST`	Malformed request or invalid request shape
`401`	`UNAUTHORIZED`	Missing or invalid API key
`422`	`VALIDATION_ERROR`	Payload validation failed
`429`	`RATE_LIMITED`	Rate limit exceeded
`500`	`INTERNAL_ERROR`	Unexpected server-side failure
`502`	`UPSTREAM_ERROR`	Upstream dependency failure
`504`	`UPSTREAM_TIMEOUT`	Upstream dependency timeout

Implementation note¶

For integration logic, treat HTTP status/error.code and business outcome (assessment.overallStatus + flags[]) as two separate decision layers.