Screening and Assessment Codes

This page is the UI-mapping reference for the B2B name-screening codes.

The main endpoint to design around is POST /v1/name/screening. It returns a bundled decision across EHRA-style company-name assessment, company conflicts, trademarks, optional domains, and execution state.

POST /v1/name/assessment uses the same assessment issue-code model for the EHRA/company-name part only. In other words: the assessment issue codes listed here are shared, but screening adds extra orchestration codes such as drivers[], primaryConcern, checkStates, resultState, and executionIssues[].

How to use this page

• For POST /v1/name/screening, use top-level overallStatus and nextAction as the main workflow decision.
• Use drivers[].code and primaryConcern.code to explain why the screening outcome was reached.
• Use details.ehraCompliance.issues[].code for the exact EHRA/company-name assessment warnings and errors.
• For POST /v1/name/assessment, use issues[].code for the same EHRA/company-name assessment warnings and errors.
• Use issue severity together with your chosen riskProfile (balanced, conservative, relaxed).
• Use endpoint error codes (HTTP + error.code) for retry and client error handling.
• Use GET /v1/name/screening/catalog when you want a runtime list of screening issue codes, driver codes, enum values, and English fallback descriptions.

Code surfaces at a glance

Response surface	Endpoint	What it tells you	Best UI use
overallStatus	screening + assessment	Final business outcome after issue/risk mapping	Main decision state: continue, warn, review, or block
nextAction	screening only	Recommended downstream action for the bundled screening result	Button state, workflow routing, or queue assignment
drivers[].code	screening only	High-level reason categories that materially influenced the bundled result	Short explanation chips or decision summary
primaryConcern.code	screening only	Single strongest concern for simple UI layouts	Main alert/banner reason
details.ehraCompliance.issues[].code	screening only	Exact EHRA/company-name issue codes returned by the assessment sub-check	Detailed issue list and localized copy map
issues[].code	assessment only	Same exact EHRA/company-name issue-code catalog, without screening orchestration fields	Lightweight assessment-only UI mapping
checkStates	screening only	Whether each requested sub-check completed, failed, or was not requested	Show incomplete/partial checks
executionIssues[].code	screening only	Error code for a requested sub-check that failed inside a partial screening result	Retry messaging or operational warning
error.code	screening + assessment	Non-200 request/transport error	Retry handling, credential errors, validation errors

Recommended UI mapping

For a partner UI, maintain these copy maps:

Copy map	Source field	Typical purpose
Assessment issue copy	details.ehraCompliance.issues[].code and assessment issues[].code	Localized labels, explanations, and remediation text for exact name-rule problems
Screening driver copy	drivers[].code and primaryConcern.code	High-level outcome explanations such as "Similar company names found" or "Trademark review needed"
Endpoint/execution error copy	error.code and executionIssues[].code	Retry, support, authentication, rate-limit, and partial-result messaging

Do not display API message values as primary customer-facing text. They are English fallback/debug copy. Use stable code values as keys and render your own German or partner-specific copy.

How assessment issues affect outcomes

Assessment issue codes are produced by the EHRA/company-name assessment pipeline.

In POST /v1/name/screening, that pipeline runs when checks.ehraCompliance.enabled=true and its issues are returned at details.ehraCompliance.issues[].

In POST /v1/name/assessment, the same issues are returned directly at top-level issues[].

What riskProfile does

riskProfile does not change which assessment checks run.

It changes how triggered issues are mapped into severity levels, which then drives the final 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-derived outcomes

For the assessment sub-check, overallStatus is derived from the highest mapped severity among all triggered assessment issues:

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

Recommended product actions

overallStatus	Typical partner action
CLEAR_TO_FILE	Continue automatically
MINOR_RISKS_DETECTED	Continue with warning or operator visibility
MANUAL_REVIEW_ADVISED	Route to a manual review queue
REGISTRY_REJECTION_LIKELY	Block, require correction, or escalate before filing

Stable vs evolving fields

• Treat issue code fields, screening driver code fields, and overallStatus as the stable machine-readable integration surface.
• Treat message fields as English fallback/debug text, not as a hard-coded branching key or primary localized UI text.
• Maintain customer-facing German UI copy in your own application, keyed by stable codes.
• riskProfile can change how a triggered issue maps to severity, so branch on the final returned status and flag code, not on assumptions about one fixed severity forever.

Catalog endpoint overview

GET /v1/name/screening/catalog returns the current machine-readable code catalog for the bundled screening endpoint.

Use this page as a human-readable overview, but treat the catalog endpoint as the runtime source of truth when building copy maps or automated coverage checks.

The catalog response has three practical groups:

Catalog group	Fields	Why it matters
Assessment issue catalog	assessmentIssueCodes, assessmentIssueSeverities, assessmentIssueCategories	Exact EHRA/company-name warning and error codes to map in your UI
Screening orchestration catalog	driverCodes, driverSources, driverSeverities, overallStatuses, resultStates, nextActions, checkStates, riskLevels	Bundled screening outcome, routing, and partial-result semantics
Error catalog	errorCodes	Non-200 error handling and screening sub-check execution failures

Assessment issue codes

These values can appear in:

• POST /v1/name/screening under details.ehraCompliance.issues[].code
• POST /v1/name/assessment under issues[].code

This is the one shared assessment issue-code catalog. The message column mirrors the English fallback/debug description returned by the catalog endpoint.

Code	Default severity	Category	English description	Example trigger
ERR_PROHIBITED_SYMBOL	ERROR	SYNTAX	The name contains prohibited symbols or unsupported special characters.	Alpen Data # AG contains an unsupported symbol.
ERR_INVALID_PUNCTUATION	ERROR	SYNTAX	The name contains invalid punctuation structure.	A.G. Muster AG uses prohibited punctuation in the legal-form area.
ERR_MULTIPLE_SPACES	ERROR	SYNTAX	Only a single word space is allowed between tokens.	Alpen Data AG contains two spaces between words.
ERR_NON_LATIN_CHARACTERS	ERROR	SYNTAX	The name contains non-Latin alphabetic characters.	A submitted name includes Cyrillic, Greek, or another non-Latin script.
ERR_MISSING_LEGAL_FORM	ERROR	LEGAL_FORM	The legal form is missing or not recognizable in the primary name.	Alpen Data is submitted for stock_corporation without AG/SA context.
ERR_MULTIPLE_LEGAL_FORMS	ERROR	LEGAL_FORM	Multiple legal forms were detected in the primary name.	Alpen Data AG GmbH contains more than one legal form.
ERR_HIDDEN_LEGAL_FORM	ERROR	LEGAL_FORM	A legal-form token appears embedded in another word.	AlpenGmbH Services AG embeds GmbH inside another token.
ERR_ENGLISH_LEGAL_FORM_PRIMARY	ERROR	LEGAL_FORM	English legal-form tokens are used without Swiss-form context in the primary name.	Alpen Data LLC uses an English-style legal form for a Swiss company name.
ERR_INVALID_SOLE_PROP_SUFFIX	ERROR	LEGAL_FORM	Sole proprietorship naming includes partnership/corporate suffix indicators.	Faller Finance Partnership or AG Muster is submitted as sole_proprietorship.
ERR_SOLE_PROP_SURNAME_MISSING	ERROR	LEGAL_FORM	Sole proprietorship name does not contain the owner's surname.	Elektro Cisco with ownerSurname="Francisco" or Mueller Bäckerei with ownerSurname="Müller".
WARN_SOLE_PROP_OWNER_SURNAME_AMBIGUOUS	WARNING	LEGAL_FORM	Sole proprietorship name contains additional surname-like elements without owner clarification.	Restaurant Schönenberger, Mathys with ownerSurname="Mathys"; clarify as Restaurant Schönenberger, Inhaberin Mathys.
ERR_STANDALONE_GEOGRAPHY	ERROR	GEOGRAPHIC	The core name is a standalone geographic designation.	Zurich AG consists only of a geographic term plus legal form.
WARN_SEAT_MISMATCH	WARNING	GEOGRAPHIC	A geographic designation may not match the provided legal seat.	Basel Treuhand AG is submitted with legalSeat="Zurich".
WARN_ORIGIN_INDICATION	WARNING	GEOGRAPHIC	The name may indicate origin/provenance. If inaccurate, use may be prohibited.	Swiss Alpine Coffee AG implies a geographic or provenance claim.
ERR_TRANSLATION_MISMATCH	ERROR	TRANSLATION	Provided translated variants do not semantically match the primary name.	German and French languageVariants describe different concepts.
ERR_TRANSLATION_UNTRANSLATABLE	ERROR	TRANSLATION	Translation appears to alter untranslatable elements.	A brand-like element is translated or changed across variants.
WARN_PURELY_DESCRIPTIVE	WARNING	SEMANTIC	The name appears purely descriptive and may lack distinctiveness.	Software Consulting AG only describes the activity.
WARN_DECEPTIVE_PURPOSE	WARNING	SEMANTIC	The implied activities appear inconsistent with the statutory purpose.	Alpen Bank AG is submitted with an activity scope for bakery software.
WARN_WELL_KNOWN_BRAND_REFERENCE	WARNING	SEMANTIC	The name may reference or resemble a well-known brand and should be reviewed.	UDS Bank AG with a finance activity may be a close near-miss to UBS; Google Legal Tech GmbH directly uses a well-known brand.
WARN_FINMA_LICENSE_REQUIRED	ERROR	REGULATORY	Regulated financial terms suggest FINMA authorization may be required.	Alpen Investment Bank AG contains regulated financial wording.
WARN_GAMBLING_TERMS_GSG	WARNING	REGULATORY	Gambling-related terms were detected and may require licensing context (Geldspielgesetz Art. 6 Abs. 3).	Swiss Casino Services AG contains gambling-related wording.
WARN_HEALTH_APOTHEKE_HMG	WARNING	REGULATORY	Pharmacy-related wording was detected and may require authorization context under Swiss therapeutic products law (HMG).	Alpen Apotheke AG contains pharmacy wording.
WARN_HEALTH_CLAIM_HMG	WARNING	REGULATORY	Health-claim wording implies potentially regulated healthcare activity under Swiss therapeutic products law (HMG).	Cancer Cure Clinic AG implies a regulated health claim.
WARN_IMPLIED_INVESTMENT_OR_BANKING_ACTIVITY	WARNING	REGULATORY	Name wording implies investment/banking activity and should be manually reviewed.	Helvetic Capital Partners AG suggests investment activity.
ERR_PUBLIC_POLICY_OFFENSIVE	ERROR	SEMANTIC	The name appears offensive, discriminatory, or contrary to public order/good morals.	The semantic check finds plainly offensive or discriminatory wording.
WARN_PUBLIC_POLICY_REVIEW	WARNING	SEMANTIC	The name raises a public-interest or public-policy concern that needs review.	Sensitive wording is not clearly blocking but should be reviewed.
WARN_HFKG_ACCREDITATION_REQUIRED	WARNING	REGULATORY	Higher-education terms suggest HFKG accreditation may be required.	Zurich University Institute AG uses higher-education wording.
WARN_OFFICIAL_DESIGNATION	WARNING	REGULATORY	Official/state designation terms require careful legal context review.	Federal Registry Services AG suggests official status.
ERR_PROTECTED_INTL_ORG_STRICT	ERROR	REGULATORY	Protected international organization names/sigils were detected.	A name uses a strictly protected organization designation such as UN.
WARN_PROTECTED_INTL_ORG_AMBIGUOUS	WARNING	REGULATORY	An ambiguous protected organization sigil was detected and requires manual review.	A short acronym could refer to a protected international organization.

Examples are illustrative

The examples above are intentionally short and may not be the only way to trigger a code. Use them as UI-copy and QA guidance, not as an exhaustive legal test suite.

Sole proprietorship surname checks

For legalForm="sole_proprietorship", send ownerSurname as the owner's current official family name.

The assessment logic treats ownerSurname as the authoritative family-name field. Matching uses Unicode-aware normalization and casefolding for comparison, but it does not transliterate or strip diacritics. Umlauts and accents remain legally significant: ü, ä, ö, é, è, à, and similar characters are not treated as ue, ae, oe, e, or a.

• Müller Bäckerei with ownerSurname="Müller" can pass the surname check; Mueller Bäckerei with ownerSurname="Müller" triggers ERR_SOLE_PROP_SURNAME_MISSING.
• Café Favre with ownerSurname="Favre" can pass the surname check, but an accented official family name must appear with its official accents.
• Elektro Cisco with ownerSurname="Francisco" is flagged because the official family name has been shortened or altered.
• Alvarez Diaz Gonzales Rodriguez Consulting can pass with ownerSurname="Alvarez Diaz Gonzales Rodriguez"; Alvarez Consulting does not satisfy that official multi-part family name.
• Muster-Hugi Beratung matches ownerSurname="Muster-Hugi", while Muster Hugi Beratung matches ownerSurname="Muster Hugi". The two spellings are not treated as interchangeable.

If the name includes another surname-like element in addition to the owner surname, the API may return WARN_SOLE_PROP_OWNER_SURNAME_AMBIGUOUS unless the name clarifies the proprietor, for example with wording such as Inhaber, Inhaberin, titulaire, titolare, or owner.

Screening driver codes

These values can appear in:

• drivers[].code
• primaryConcern.code

They summarize why the bundled screening result reached its outcome.

Code	Source	Default severity	English description	Typical partner handling
ASSESSMENT_WARNING_FLAGS	assessment	warning	Assessment warning flags contributed to the screening result.	Show warning copy and allow continuation if your workflow permits.
ASSESSMENT_REVIEW_FLAGS	assessment	review	Assessment review flags contributed to the screening result.	Route to manual review or require operator confirmation.
ASSESSMENT_BLOCKING_FLAGS	assessment	block	Assessment blocking flags contributed to the screening result.	Block automatic progression or require correction before filing.
IDENTITY_COMPANY_MATCH	conflicts	block	An identical company registry match contributed to the screening result.	Treat as a strong conflict signal and stop automatic progression.
SIMILAR_COMPANY_MATCHES	conflicts	review	Similar company registry matches contributed to the screening result.	Show top registry matches and route to review when material.
TRADEMARK_MATCHES	trademarks	review	Trademark matches contributed to the screening result.	Show trademark matches and route to review based on risk/class overlap.
DOMAINS_ALREADY_REGISTERED	domains	warning	Registered domains contributed to the screening result.	Warn that exact or related domains are already registered.
REQUESTED_CHECK_FAILED	execution	review	One or more requested screening checks failed to complete.	Treat resultState=PARTIAL as incomplete and retry or review before relying on the result.

Catalog enum values

These enum arrays are also returned by GET /v1/name/screening/catalog.

Catalog field	Values	Where used
assessmentIssueSeverities	INFO, WARNING, ERROR	details.ehraCompliance.issues[].severity and POST /v1/name/assessment issues[].severity
assessmentIssueCategories	SYNTAX, LEGAL_FORM, GEOGRAPHIC, TRANSLATION, SEMANTIC, REGULATORY	details.ehraCompliance.issues[].category
overallStatuses	CLEAR_TO_FILE, MINOR_RISKS_DETECTED, MANUAL_REVIEW_ADVISED, REGISTRY_REJECTION_LIKELY	Top-level screening and assessment overallStatus
resultStates	COMPLETE, PARTIAL	Top-level screening resultState
nextActions	PROCEED, PROCEED_WITH_CAUTION, ROUTE_TO_MANUAL_REVIEW, STOP_AND_REVIEW	Top-level screening nextAction
driverSources	assessment, conflicts, trademarks, domains, execution	drivers[].source, primaryConcern.source
driverSeverities	info, warning, review, block	drivers[].severity, primaryConcern.severity
checkStates	completed, failed, not_requested	checkStates.ehraCompliance, checkStates.conflicts, checkStates.trademarks, checkStates.domains
riskLevels	High, Medium, Low	Conflict/trademark/domain risk summaries and top matches
errorCodes	VALIDATION_ERROR, INVALID_REQUEST, UNAUTHORIZED, RATE_LIMITED, UPSTREAM_ERROR, UPSTREAM_TIMEOUT, INTERNAL_ERROR	Non-200 error envelope error.code and screening sub-check errors

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 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 and execution error codes

These are request/transport errors for POST /v1/name/screening, POST /v1/name/assessment, and related partner endpoints. They are separate from successful 200 business outcomes and separate from assessment issue codes.

The same codes can also appear in screening executionIssues[].code when a requested sub-check fails and the screening response returns resultState=PARTIAL.

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 these as separate decision layers:

Layer	Fields	Meaning
Request/transport	HTTP status, error.code	Did the request execute successfully? Should the client retry or fix input/authentication?
Screening workflow	overallStatus, nextAction, drivers[], primaryConcern, resultState	What should the partner workflow do with the bundled screening result?
Assessment issue detail	details.ehraCompliance.issues[] or assessment issues[]	Which exact EHRA/company-name warnings/errors should be mapped to UI copy?