{ "openapi": "3.1.0", "info": { "title": "BUMIT API", "version": "0.10.5", "description": "Trust infrastructure for business and autonomous transactions. BUMIT verifies Swiss businesses using authoritative evidence and returns deterministic, machine-readable decisions, reason codes, freshness and provenance.\n\n## Data sources and attribution\n\nZefix (Swiss Central Business Name Index / Commercial Register) is the source of the company-register data returned by this API. Every Zefix-derived fact carries `source: ZEFIX`, a retrieval timestamp, the source record identifier where available and an official-source reference.\n\n## No guarantee\n\nZefix does not guarantee the completeness, accuracy or availability of this data. Upstream information may be incomplete, delayed, unavailable or erroneous.\n\n## No legal effect\n\nZefix-reported information has no legal effect. It is registry-derived information retrieved from Zefix, not a legally certified, binding or guaranteed statement of legal status.\n\n## BUMIT-derived fields\n\nBUMIT normalizes, validates and enriches source data. Normalized names, mapped status enums, freshness flags, coverage statements and PASS/REVIEW/FAIL/UNKNOWN decisions are BUMIT-derived values, reported under `bumit_derived_values` and `decision_origin`, and are NOT fields published by Zefix. BUMIT logic does not change the legal status of the underlying Zefix data.\n\n## Freshness\n\nResponses expose `freshness` (`observed_at`, `retrieved_at`, `source_timestamp`, `age_seconds`, `max_age_hours`, `stale`, `served_from_cache`, `source_state`, `upstream_status`). BUMIT is cache-first: sufficiently fresh stored data is reused instead of calling Zefix, and cached data is never presented as a fresh verification. `source_state` is one of LIVE (produced by a successful upstream call for this request), CACHED (served from local storage within the freshness window), STALE (older than `max_age_hours`), DEGRADED (upstream not confirmed available) or UNAVAILABLE (no observation at all).\n\n## Decision semantics\n\n`decision` is BUMIT-derived and is one of PASS, REVIEW, FAIL, UNKNOWN. It is produced by a versioned verification profile (`profile`), whose MANDATORY checks alone determine the outcome: any mandatory FAIL yields FAIL, otherwise any mandatory REVIEW yields REVIEW, otherwise any mandatory UNKNOWN yields UNKNOWN, otherwise PASS. Optional and informational findings stay visible in `checks`, `reason_codes`, `claims` and `coverage` but never compensate for unresolved or adverse mandatory evidence. No weighted score, majority vote, positive-signal counting, fuzzy decisioning or LLM is used. UNKNOWN means the evidence required for a conclusion was missing, unavailable, stale or unusable — explicitly NOT a negative and NEVER a positive result. PASS means only that the configured profile's applicable mandatory checks were satisfied: it does not mean safe to transact, trustworthy, risk-free, solvent, legally approved, complete KYB, free of sanctioned owners or controllers, or confirmed signatory authority. See `x-verification-profiles`.\n\n## Reason codes\n\n`reason_codes` on verification results and `error.reason_code` on failures are stable machine-readable identifiers. Human-readable `message` text may change at any time; machines must key on codes. `error.retryable` states whether repeating the identical request may succeed.\n\n## Evidence classification\n\nEvery claim carries `claim_type`: SOURCE_FACT (explicitly published by the source), NORMALIZED (deterministic transformation of a source fact), DERIVED (deterministic BUMIT conclusion), INFERRED (probabilistic, not stated by the source) or UNAVAILABLE (required evidence missing). `inference_used` is true if and only if `claim_type` is INFERRED, so an inferred value can never be presented as a source fact. `confidence` appears only on INFERRED claims; deterministic authoritative facts never receive an invented confidence score. Nothing in the current implementation produces INFERRED claims.\n\n## Capabilities\n\n`x-capabilities` lists the stable BUMIT capability taxonomy. A capability being listed does NOT mean it is operationally available. Query `/api/v1/capabilities` for deployment-specific support and availability; fixture-only capabilities remain unavailable for production evidence.\n\n## Idempotency\n\nVerification accepts an optional `Idempotency-Key` request header. Within the retention window, the same key with the same request replays the stored response (`Idempotent-Replay: true`) instead of repeating the operation or upstream work. Reusing a key with a different request returns BAD_REQUEST. No payment or charging behaviour exists." }, "servers": [ { "url": "https://bumit.ai", "description": "Current deployment" } ], "paths": { "/api/health": { "get": { "operationId": "getHealth", "summary": "Service liveness", "responses": { "200": { "description": "Service is up", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "service" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] }, "service": { "type": "string", "enum": [ "bumit" ] } } } } } } } } }, "/api/v1/capabilities": { "get": { "operationId": "listCapabilities", "summary": "Capability support and operational availability", "description": "Derived from the canonical BUMIT capability registry and local source configuration. Fixture-only capabilities are never reported as available.", "responses": { "200": { "description": "Public capability contract", "content": { "application/json": { "schema": { "type": "object", "required": [ "capabilities", "legal_effect" ], "properties": { "capabilities": { "type": "array", "items": { "type": "object" } }, "legal_effect": { "const": false } } } } } } } } }, "/api/v1/status": { "get": { "operationId": "getPublicStatus", "summary": "Public service, source, and capability status", "description": "Reports public-safe local state without making live upstream requests. Service liveness, source state, and capability availability are separate.", "responses": { "200": { "description": "Public operational status", "content": { "application/json": { "schema": { "type": "object", "required": [ "service", "sources", "capabilities", "semantics" ], "properties": { "service": { "type": "object" }, "sources": { "type": "array", "items": { "type": "object" } }, "capabilities": { "type": "array", "items": { "type": "object" } }, "semantics": { "type": "object" } } } } } } } } }, "/api/v1/company/search": { "get": { "operationId": "searchCompanies", "summary": "Search Swiss companies by name (Zefix)", "description": "Returns register candidates from the Zefix central business name index. A match is not a verification result.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Company name, at least three characters.", "schema": { "type": "string", "minLength": 3 } }, { "name": "canton", "in": "query", "required": false, "description": "Two-letter canton abbreviation.", "schema": { "type": "string" } }, { "name": "activeOnly", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Candidate companies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySearchResult" } } } }, "400": { "description": "The search term is too short", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "501": { "description": "No authoritative source is configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotImplemented" } } } }, "503": { "description": "The commercial register is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/company/{uid}": { "get": { "operationId": "getCompany", "summary": "Normalized company record (Zefix)", "description": "Returns the BUMIT canonical company record with provenance and freshness.", "parameters": [ { "name": "uid", "in": "path", "required": true, "description": "Swiss UID in canonical or compact form, e.g. CHE-123.456.789.", "schema": { "type": "string", "example": "CHE-123.456.789" } } ], "responses": { "200": { "description": "Normalized company record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyResult" } } } }, "404": { "description": "No legal entity is registered for this UID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "The UID is not structurally valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "501": { "description": "No authoritative source is configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotImplemented" } } } }, "503": { "description": "The commercial register is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/api/v1/company/{uid}/verify": { "get": { "operationId": "verifyCompany", "summary": "Verify a Swiss company (partial coverage)", "description": "Establishes UID validity, entity existence, registered name, legal form, register status, Zefix provenance and freshness. It does NOT cover sanctions, VAT, FINMA, address validation, insolvency or complete KYB, and never returns PASS for complete verification.", "parameters": [ { "name": "uid", "in": "path", "required": true, "description": "Swiss UID in canonical or compact form, e.g. CHE-123.456.789.", "schema": { "type": "string", "example": "CHE-123.456.789" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional retry-safety key. The same key with the same request replays the stored response instead of repeating the operation.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Partial verification result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResult" } } } }, "400": { "description": "The Idempotency-Key was reused for a different request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "The UID is not structurally valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "501": { "description": "No authoritative source is configured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotImplemented" } } } } } } }, "/api/v1/company/{uid}/events": { "get": { "operationId": "getCompanyEvents", "summary": "Historical commercial-register publications (SHAB/SOGC) for a UID", "description": "Returns stored SHAB/SOGC publications for one canonical UID, newest publication first.\n\nA publication is historical evidence of what was published at a point in time. It never states current company state (`describes_current_state` is always false) and never establishes registered persons or signature authority (`signatory_authority_covered` is always false). Publication prose is retained only as raw source evidence and is never interpreted: no claim in this response is derived from free text, and no INFERRED claim is produced.\n\nEvent types are limited to those a structured publication element establishes deterministically: REGISTRATION, DELETION, OTHER_HR_PUBLICATION and UNCLASSIFIED. `classification_basis` names the structured element used.\n\nCompany linkage uses the canonical UID only; BUMIT never matches a company by name. `company_link_status` is `LINKED` only when the canonical UID resolved to a stored BUMIT company, `UID_IDENTIFIED` when the publication carries a structured UID that is not (yet) resolved to a stored company, and `UNRESOLVED` when the publication carries no structured UID at all.\n\nLive and scheduled SHAB ingestion is currently disabled, so coverage is limited to publications already ingested and an empty result is never evidence that no publication exists (`reason_codes: [INSUFFICIENT_EVIDENCE]`).", "parameters": [ { "name": "uid", "in": "path", "required": true, "description": "Swiss UID in canonical or compact form, e.g. CHE-123.456.789.", "schema": { "type": "string", "example": "CHE-123.456.789" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of publications to return. Default 100, maximum 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } } ], "responses": { "200": { "description": "Chronological publication history with provenance, attribution and coverage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyEventsResponse" } } } }, "400": { "description": "Invalid limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Structurally invalid UID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "The gazette source is not configured in this deployment; the capability is supported but unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/company/{uid}/sanctions": { "get": { "operationId": "getCompanySanctions", "summary": "Direct SECO sanctions screening for a UID", "description": "Screens the BUMIT-held registered company name directly against entity targets in the stored SECO consolidated sanctions dataset.\n\nScope is DIRECT_SECO_LIST_SCREENING: direct subjects only. SECO's list concerns directly sanctioned subjects and establishes no ownership or control relationships, so `ownership_control_checked` is always false.\n\nA `check_state` of CLEAR means only that no direct candidate match was found in the dataset BUMIT checked. It does NOT mean the company is not sanctioned, that no sanctioned party owns or controls it, that other sanctions regimes are clear, or that it is safe to transact. This endpoint never asserts that a company is not sanctioned.\n\nMatching is deterministic code with no similarity score, no threshold and no LLM. Candidate generation (exact normalized name, equal normalized token set, legal-form-reduced name) is separate from match classification. CONFIRMED_MATCH remains in the contract but is unreachable: SECO publishes no structured company identifier, so no authoritative identity rule exists that could confirm an entity match, and name evidence alone must never confirm.\n\nCurrent listing state is DERIVED from structured modification history, never from a target's mere presence in the whole list; a de-listed target is still reported as a candidate with `listing_state: DE_LISTED`.\n\nAn unavailable, schema-unsupported or stale dataset, or a missing register name, yields UNKNOWN with SANCTIONS_CHECK_INCOMPLETE — never CLEAR. Live and scheduled SECO ingestion is disabled, so coverage is limited to the dataset already ingested.", "parameters": [ { "name": "uid", "in": "path", "required": true, "description": "Swiss UID in canonical or compact form, e.g. CHE-123.456.789.", "schema": { "type": "string", "example": "CHE-123.456.789" } } ], "responses": { "200": { "description": "Sanctions check state with scope, coverage, matching ruleset, candidate evidence, claims, freshness and provenance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanySanctionsResponse" } } } }, "404": { "description": "No legal entity is registered for this UID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Structurally invalid UID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "No authoritative source is configured in this deployment; the capability is supported but unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotImplemented" } } } } } } }, "/api/v1/company/{uid}/finma": { "get": { "operationId": "getCompanyFinma", "summary": "FINMA authorisation-list membership and warning-list candidates for a UID", "description": "Returns TWO independent checks in strictly separate sections. They are never merged into a combined FINMA status, and neither is a legal conclusion.\n\nauthorisation (FINMA_AUTHORISATION_CHECK): membership is FOUND_IN_FINMA_LIST, NOT_FOUND_IN_FINMA_LIST or UNKNOWN. FOUND_IN_FINMA_LIST means only that the canonical Swiss UID appears in the stored FINMA authorisation-list snapshot; it never means authorised, licensed, supervised, compliant or safe, and it says nothing about permitted activities. NOT_FOUND_IN_FINMA_LIST means only that the UID was absent from that snapshot; it never means not authorised. Linkage is exact canonical UID equality only — no name, city, branch, commercial-register, fuzzy or LLM inference. Multiple authorisation-category rows for one UID are all returned and never collapsed; FINMA's own category terminology is preserved verbatim in four languages as source facts.\n\nwarning (FINMA_WARNING_CHECK): result is NO_DIRECT_LIST_MATCH, POSSIBLE_LIST_MATCH or UNKNOWN. There is no confirmed state: FINMA publishes no authoritative identifier for warning entries, so identity can never be confirmed, and an exact normalized-name equality yields at most POSSIBLE_LIST_MATCH. Only entries whose subject type the source explicitly marks as a company are screened: natural-person entries are excluded from ingestion entirely and entries with an unestablished subject type are counted but never screened, because entity type is never inferred from a name, a legal-form suffix, the commercial-register text or a jurisdiction. NO_DIRECT_LIST_MATCH therefore means only that no direct match was produced among the entries eligible for company screening under the current BUMIT rules; it does not mean the name is absent from the complete FINMA warning list, and it never means the absence of regulatory concern. A warning-list entry never means illegal activity, fraud, an unlicensed business or sanctions. Matching is deterministic with no score, no threshold, no edit distance and no LLM. The warning-list Date is undocumented by FINMA and is exposed verbatim as source_date_value with source_date_dimension: UNKNOWN; it is never renamed and never used for ordering or state derivation.\n\nAbsence from either list is never treated as a removal, withdrawal or revocation. An unavailable, invalid or stale dataset, or an unusable UID or missing register name, yields UNKNOWN — never a negative finding.\n\nLive FINMA ingestion is disabled and no retrieval path exists; this deployment serves synthetic fixture datasets, marked evidence_class: SYNTHETIC_FIXTURE.", "parameters": [ { "name": "uid", "in": "path", "required": true, "description": "Swiss UID in canonical or compact form, e.g. CHE-123.456.789.", "schema": { "type": "string", "example": "CHE-123.456.789" } } ], "responses": { "200": { "description": "Two separate FINMA check results with scope, coverage, matching ruleset, claims, freshness, provenance and attribution." }, "404": { "description": "No legal entity is registered for this UID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Structurally invalid UID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "No authoritative source is configured in this deployment; the capability is supported but unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotImplemented" } } } } } } }, "/api/v1/company/{uid}/lei": { "get": { "operationId": "getCompanyLei", "summary": "GLEIF Level 1 LEI records linked to a Swiss UID by exact identifier equality", "description": "Returns the GLEIF Level 1 records whose Swiss commercial-register identifier exactly equals the queried canonical UID. result is FOUND, NOT_FOUND, MULTIPLE_RECORDS or UNKNOWN.\n\nLinkage (LEI_LOOKUP): deterministic identifier equality only. A record matches when entity.registeredAt.id is exactly RA000548 AND entity.registeredAs is exactly the compact form of the queried canonical UID. GLEIF publishes the Swiss identifier compact, without the CHE- dash and without dot separators (for example CHE102753938); BUMIT applies that formatting transform on the query side only and never rewrites the stored source value. registration.validatedAt and registration.validatedAs are reported as corroborating evidence and are never required for linkage. No legal name, address, city, legal-form, punctuation-heuristic, similarity-score, fuzzy or LLM matching exists anywhere in this path.\n\nResult semantics: FOUND means one exact record exists — never that the company is active, solvent, authorised, compliant or safe to transact with. NOT_FOUND means only that no exact record existed in the stored GLEIF data, is emitted only after a successful lookup against usable data, and never means the company does not exist. MULTIPLE_RECORDS returns every exact record and resolves none: no selection is made on registration status, dates, name similarity or ordering, because a Swiss UID is not assumed to map to exactly one LEI. UNKNOWN covers an unavailable, invalid, malformed or stale dataset and an unusable UID, and is never a negative finding.\n\nStatuses: entity.status and registration.status are two independent questions, kept separate and verbatim, including unknown or future source values. An ISSUED LEI is not COMPANY_ACTIVE; a LAPSED LEI is neither COMPANY_INACTIVE nor COMPANY_DOES_NOT_EXIST; RETIRED carries only its documented GLEIF meaning. There is no LEI_OK, LEI_TRUSTED, SAFE or VERIFIED_SAFE state.\n\nLevel 2: no parent-relationship engine is implemented. A GLEIF accounting-consolidating parent is not a beneficial owner, not a UBO and not a controlling natural person, and a reporting exception such as NO_KNOWN_PERSON is never transformed into NO_PARENT, NO_OWNER or NO_UBO. Reporting exceptions are retained verbatim and their composite identifiers are stored whole, never parsed.\n\nProvenance separates BUMIT's retrieved_at from GLEIF source dates: registration.lastUpdateDate is a source field and is never treated as a retrieval time, and meta.goldenCopy.publishDate is retained only where GLEIF actually supplied it and is never a sole cache validator.\n\nGLEIF live retrieval is not implemented: there is no request path, no Golden Copy download, no delta synchronisation and no scheduler. This deployment serves synthetic fixture datasets, marked evidence_class: SYNTHETIC_FIXTURE.", "parameters": [ { "name": "uid", "in": "path", "required": true, "description": "Swiss UID in canonical or compact form, e.g. CHE-123.456.789.", "schema": { "type": "string", "example": "CHE-123.456.789" } } ], "responses": { "200": { "description": "LEI lookup result with linkage descriptor, every exact record, coverage, matching ruleset, claims, freshness, provenance and attribution." }, "404": { "description": "No legal entity is registered for this UID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Structurally invalid UID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "No authoritative source is configured in this deployment; the capability is supported but unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotImplemented" } } } } } } }, "/api/v1/company/{uid}/vat": { "get": { "operationId": "getCompanyVat", "summary": "Swiss UID register VAT registration state for a canonical UID", "description": "Returns what the Swiss UID register record BUMIT holds says about this canonical UID's VAT registration. result is VAT_ACTIVE, VAT_INACTIVE, NO_VAT_REGISTRATION or UNKNOWN.\n\nLinkage (VAT_VERIFY): exact canonical UID equality only. No legal name, address, city, punctuation-heuristic, similarity-score, fuzzy or LLM matching exists anywhere in this path, and a VAT status is never constructed from a company UID alone.\n\nThe UID register may associate an entity with a VAT UID that differs from its company UID, including branch and VAT-group structures. BUMIT retains both identifiers independently as source facts, reports any canonical form separately as a normalized value, and never constructs a VAT status from a company UID alone.\n\nSeparate questions, never merged: UID assignment and structural validity, the source entity status, and the VAT registration state. A structurally valid or assigned UID does not mean the company is active or VAT registered; an inactive or deleted company does not make its UID invalid; an inactive VAT registration does not mean the company is inactive. VAT_ACTIVE is not safe-to-transact and not sanctions clearance.\n\nThe normalized VAT result comes from an explicitly versioned mapping of source status values. A source status the mapping does not list — including an unknown or future value — yields UNKNOWN and is never silently mapped to active or inactive. The source value itself is always reported verbatim alongside the normalized result.\n\nAbsence of evidence is never evidence of absence. NO_VAT_REGISTRATION requires the source to explicitly state that no registration exists. A missing record, silent VAT block, malformed payload, stale dataset, unavailable source or contradictory evidence is UNKNOWN.\n\nProvenance separates BUMIT's retrieved_at from source-published dates: the VAT entry date and the VAT end or liquidation date are source fields and are never treated as retrieval times.\n\nLive retrieval is not implemented: there is no SOAP request path, no scheduler and no polling. This deployment serves synthetic fixture datasets, marked evidence_class: SYNTHETIC_FIXTURE.", "parameters": [ { "name": "uid", "in": "path", "required": true, "description": "Swiss UID in canonical or compact form, e.g. CHE-123.456.789.", "schema": { "type": "string", "example": "CHE-123.456.789" } } ], "responses": { "200": { "description": "VAT verification result with the source VAT identifier and status verbatim, source dates, normalized result, coverage, matching ruleset, claims, freshness, provenance and attribution." }, "422": { "description": "Structurally invalid UID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "No authoritative source is configured in this deployment; the capability is supported but unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotImplemented" } } } } } } }, "/api/v1/address/verify": { "get": { "operationId": "verifyAddress", "summary": "Correspondence of an address with the official Swiss building-address directory", "description": "Reports whether the queried address components correspond exactly to an entry in the official Swiss directory of building addresses (swisstopo) snapshot BUMIT holds. result is OFFICIAL_ADDRESS, PLANNED_ADDRESS, OUTDATED_ADDRESS, NOT_FOUND, MULTIPLE_MATCHES or UNKNOWN. No company UID is required or used.\n\nADDRESS_VERIFY establishes correspondence with the official Swiss building-address directory only. It does not establish that a company is registered, domiciled or operating at the address, that mail is deliverable there, that any company is active, or that a transaction is safe. No company register address is compared in this phase.\n\nADR_EGAID (building address), BDG_EGID (building), ADR_EDID (entrance), STR_ESID (street) and COM_FOSNR (municipality) are five separate federal identifiers. BUMIT retains each independently and verbatim, never derives one from another and never manufactures one.\n\nADR_STATUS (planned / real / outdated) and ADR_OFFICIAL (a boolean) are two separate source fields. BUMIT reports both verbatim and never collapses one into the other: a real status alone does not make an address official, and an official flag never erases the published status.\n\nThe normalized address result comes from an explicitly versioned mapping of the source ADR_STATUS value together with the separate ADR_OFFICIAL boolean. ADR_STATUS and ADR_OFFICIAL are never collapsed: a real status alone does not make an address official, and an official flag never erases the published status. A status the mapping does not list — including an unknown or future value — yields UNKNOWN and is never silently mapped.\n\nMatching is deterministic exact equality on normalized address components: street label, house number, postcode and locality. Normalization is formatting only — Unicode NFC, whitespace, comparison-case, canonical four-digit postcode and conservative house-number formatting. A multilingual street label is preserved whole and additionally exposes exact per-language segment keys. No fuzzy matching, edit distance, similarity score, embedding, LLM, address guessing or nearest-geographic selection exists in this path, and several matches are reported as MULTIPLE_MATCHES rather than resolved.\n\nAbsence of evidence is never evidence of absence. NOT_FOUND is emitted only after a deterministic lookup against a usable, sufficiently current dataset, and means only that no entry matched in the data BUMIT checked. A missing, malformed, stale, contradictory or unavailable dataset is UNKNOWN.\n\nProvenance separates BUMIT's retrieved_at from source-published dates: the source modification date and any dataset publication date are source fields and are never treated as retrieval times.\n\nLive retrieval is not implemented: there is no download, STAC, REST or SPARQL request path, no scheduler and no polling, and no request-per-verification path exists. This deployment serves synthetic fixture datasets, marked evidence_class: SYNTHETIC_FIXTURE.", "parameters": [ { "name": "street", "in": "query", "required": true, "description": "Street label. A multilingual label may be given whole or as one language segment.", "schema": { "type": "string", "minLength": 1 } }, { "name": "house_number", "in": "query", "required": true, "description": "House number including any suffix, for example 12A.", "schema": { "type": "string", "minLength": 1 } }, { "name": "postcode", "in": "query", "required": true, "description": "Four-digit Swiss postcode. Any other form is unusable and yields UNKNOWN.", "schema": { "type": "string", "minLength": 1 } }, { "name": "locality", "in": "query", "required": true, "description": "Locality as published with the postcode.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Address verification result with the source status and the separate official flag verbatim, the federal identifiers ADR_EGAID, BDG_EGID, ADR_EDID, STR_ESID and COM_FOSNR independently, the normalized query, coverage, matching ruleset, claims, freshness, provenance and attribution." }, "400": { "description": "A required address component is missing; BUMIT never widens a partial query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "501": { "description": "No authoritative source is configured in this deployment; the capability is supported but unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotImplemented" } } } } } } }, "/api/v1/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "This specification", "responses": { "200": { "description": "OpenAPI document" } } } } }, "components": { "schemas": { "Meta": { "type": "object", "required": [ "service", "api_version", "trace_id", "generated_at" ], "properties": { "service": { "type": "string" }, "api_version": { "type": "string" }, "trace_id": { "type": "string", "format": "uuid" }, "generated_at": { "type": "string", "format": "date-time" } } }, "NotImplemented": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "string", "enum": [ "NOT_IMPLEMENTED" ] }, "reason_code": { "$ref": "#/components/schemas/ReasonCode" }, "retryable": { "type": "boolean", "enum": [ false ] }, "capability": { "oneOf": [ { "$ref": "#/components/schemas/CapabilityStatus" }, { "$ref": "#/components/schemas/UnsupportedCapability" } ] }, "message": { "type": "string" }, "uid": { "type": "string" }, "ruleset_version": { "type": "string" }, "configured_sources": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "ApiError": { "type": "object", "required": [ "status", "error" ], "properties": { "status": { "type": "string", "enum": [ "ERROR" ] }, "error": { "type": "object", "required": [ "code", "reason_code", "message", "retryable" ], "properties": { "code": { "type": "string" }, "reason_code": { "$ref": "#/components/schemas/ReasonCode" }, "message": { "type": "string", "description": "Human-readable. Not a stable contract." }, "retryable": { "type": "boolean" }, "details": { "type": "object", "additionalProperties": true } } }, "trace_id": { "type": "string", "format": "uuid" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Decision": { "type": "string", "enum": [ "PASS", "REVIEW", "FAIL", "UNKNOWN" ], "description": "BUMIT-derived outcome. UNKNOWN means required evidence was missing, unavailable or not covered; it is never a positive result. Missing required evidence never yields PASS." }, "ReasonCode": { "type": "string", "enum": [ "INVALID_UID", "COMPANY_NOT_FOUND", "SOURCE_NOT_CONFIGURED", "SOURCE_UNAVAILABLE", "SOURCE_TIMEOUT", "SOURCE_RATE_LIMITED", "STALE_EVIDENCE", "INSUFFICIENT_EVIDENCE", "CAPABILITY_NOT_SUPPORTED", "CAPABILITY_NOT_AVAILABLE", "AUTHENTICATION_REQUIRED", "ACCESS_DENIED", "RATE_LIMITED", "UPSTREAM_DEGRADED", "INTERNAL_ERROR", "BAD_REQUEST", "PARTIAL_COVERAGE", "SANCTIONS_NO_DIRECT_MATCH", "SANCTIONS_POSSIBLE_MATCH", "SANCTIONS_CONFIRMED_MATCH", "SANCTIONS_DATA_UNAVAILABLE", "SANCTIONS_DATA_STALE", "SANCTIONS_SCHEMA_UNSUPPORTED", "SANCTIONS_CHECK_INCOMPLETE", "FINMA_LIST_UID_MATCH", "FINMA_LIST_UID_NOT_FOUND", "FINMA_LIST_UID_UNUSABLE", "FINMA_AUTHORISATION_DATA_UNAVAILABLE", "FINMA_AUTHORISATION_DATA_STALE", "FINMA_AUTHORISATION_DATA_INVALID", "FINMA_AUTHORISATION_CHECK_INCOMPLETE", "FINMA_WARNING_NO_DIRECT_MATCH", "FINMA_WARNING_POSSIBLE_MATCH", "FINMA_WARNING_DATA_UNAVAILABLE", "FINMA_WARNING_DATA_STALE", "FINMA_WARNING_DATA_INVALID", "FINMA_WARNING_CHECK_INCOMPLETE", "LEI_RECORD_FOUND", "LEI_RECORD_NOT_FOUND", "LEI_MULTIPLE_RECORDS", "LEI_LINKAGE_IDENTIFIER_UNUSABLE", "LEI_DATA_UNAVAILABLE", "LEI_DATA_INVALID", "LEI_DATA_STALE", "LEI_LOOKUP_INCOMPLETE", "VAT_ACTIVE_REGISTRATION", "VAT_INACTIVE_REGISTRATION", "VAT_NO_REGISTRATION", "VAT_STATUS_UNRECOGNISED", "VAT_EVIDENCE_CONTRADICTORY", "VAT_RECORD_NOT_FOUND", "VAT_MULTIPLE_SOURCE_RECORDS", "VAT_SUBJECT_UID_UNUSABLE", "VAT_DATA_UNAVAILABLE", "VAT_DATA_INVALID", "VAT_DATA_STALE", "VAT_CHECK_INCOMPLETE", "ADDRESS_OFFICIAL_MATCH", "ADDRESS_PLANNED_MATCH", "ADDRESS_OUTDATED_MATCH", "ADDRESS_NOT_FOUND", "ADDRESS_MULTIPLE_MATCHES", "ADDRESS_QUERY_UNUSABLE", "ADDRESS_STATUS_MISSING", "ADDRESS_STATUS_UNRECOGNISED", "ADDRESS_OFFICIAL_FLAG_NOT_SET", "ADDRESS_EVIDENCE_CONTRADICTORY", "ADDRESS_DATA_UNAVAILABLE", "ADDRESS_DATA_INVALID", "ADDRESS_DATA_STALE", "ADDRESS_CHECK_INCOMPLETE", "MANDATORY_CHECK_FAILED", "MANDATORY_CHECK_REVIEW", "MANDATORY_CHECK_UNKNOWN", "VERIFICATION_PROFILE_SATISFIED" ], "description": "Stable machine-readable reason identifier.", "x-active": [ "INVALID_UID", "COMPANY_NOT_FOUND", "SOURCE_NOT_CONFIGURED", "SOURCE_UNAVAILABLE", "SOURCE_TIMEOUT", "SOURCE_RATE_LIMITED", "STALE_EVIDENCE", "INSUFFICIENT_EVIDENCE", "CAPABILITY_NOT_AVAILABLE", "AUTHENTICATION_REQUIRED", "ACCESS_DENIED", "UPSTREAM_DEGRADED", "INTERNAL_ERROR", "BAD_REQUEST", "PARTIAL_COVERAGE", "SANCTIONS_NO_DIRECT_MATCH", "SANCTIONS_POSSIBLE_MATCH", "SANCTIONS_DATA_UNAVAILABLE", "SANCTIONS_DATA_STALE", "SANCTIONS_SCHEMA_UNSUPPORTED", "SANCTIONS_CHECK_INCOMPLETE", "FINMA_LIST_UID_MATCH", "FINMA_LIST_UID_NOT_FOUND", "FINMA_LIST_UID_UNUSABLE", "FINMA_AUTHORISATION_DATA_UNAVAILABLE", "FINMA_AUTHORISATION_DATA_STALE", "FINMA_AUTHORISATION_DATA_INVALID", "FINMA_AUTHORISATION_CHECK_INCOMPLETE", "FINMA_WARNING_NO_DIRECT_MATCH", "FINMA_WARNING_POSSIBLE_MATCH", "FINMA_WARNING_DATA_UNAVAILABLE", "FINMA_WARNING_DATA_STALE", "FINMA_WARNING_DATA_INVALID", "FINMA_WARNING_CHECK_INCOMPLETE", "LEI_RECORD_FOUND", "LEI_RECORD_NOT_FOUND", "LEI_MULTIPLE_RECORDS", "LEI_LINKAGE_IDENTIFIER_UNUSABLE", "LEI_DATA_UNAVAILABLE", "LEI_DATA_INVALID", "LEI_DATA_STALE", "LEI_LOOKUP_INCOMPLETE", "VAT_ACTIVE_REGISTRATION", "VAT_INACTIVE_REGISTRATION", "VAT_NO_REGISTRATION", "VAT_STATUS_UNRECOGNISED", "VAT_EVIDENCE_CONTRADICTORY", "VAT_RECORD_NOT_FOUND", "VAT_MULTIPLE_SOURCE_RECORDS", "VAT_SUBJECT_UID_UNUSABLE", "VAT_DATA_UNAVAILABLE", "VAT_DATA_INVALID", "VAT_DATA_STALE", "VAT_CHECK_INCOMPLETE", "ADDRESS_OFFICIAL_MATCH", "ADDRESS_PLANNED_MATCH", "ADDRESS_OUTDATED_MATCH", "ADDRESS_NOT_FOUND", "ADDRESS_MULTIPLE_MATCHES", "ADDRESS_QUERY_UNUSABLE", "ADDRESS_STATUS_MISSING", "ADDRESS_STATUS_UNRECOGNISED", "ADDRESS_OFFICIAL_FLAG_NOT_SET", "ADDRESS_EVIDENCE_CONTRADICTORY", "ADDRESS_DATA_UNAVAILABLE", "ADDRESS_DATA_INVALID", "ADDRESS_DATA_STALE", "ADDRESS_CHECK_INCOMPLETE", "MANDATORY_CHECK_FAILED", "MANDATORY_CHECK_REVIEW", "MANDATORY_CHECK_UNKNOWN", "VERIFICATION_PROFILE_SATISFIED" ] }, "ClaimType": { "type": "string", "enum": [ "SOURCE_FACT", "NORMALIZED", "DERIVED", "INFERRED", "UNAVAILABLE" ], "description": "SOURCE_FACT published by the source; NORMALIZED deterministic transformation; DERIVED deterministic BUMIT conclusion; INFERRED probabilistic and not stated by the source; UNAVAILABLE required evidence missing." }, "SourceState": { "type": "string", "enum": [ "LIVE", "CACHED", "STALE", "DEGRADED", "UNAVAILABLE" ] }, "UpstreamStatus": { "type": "string", "enum": [ "AVAILABLE", "NOT_CHECKED", "DEGRADED", "UNAVAILABLE", "NOT_CONFIGURED" ], "description": "Current upstream condition. NOT_CHECKED means this request was served cache-first and never contacted the source, so no availability claim is made; it is not a failure. Pair it with upstream_checked: false and source_state: CACHED." }, "Claim": { "type": "object", "required": [ "attribute", "value", "claim_type", "inference_used" ], "description": "A classified assertion. inference_used is true if and only if claim_type is INFERRED; confidence is present only for INFERRED claims.", "properties": { "attribute": { "type": "string" }, "value": {}, "claim_type": { "$ref": "#/components/schemas/ClaimType" }, "inference_used": { "type": "boolean" }, "source": { "type": [ "string", "null" ] }, "source_record_id": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "valid_from": { "type": [ "string", "null" ] }, "valid_to": { "type": [ "string", "null" ] }, "source_hash": { "type": [ "string", "null" ] }, "confidence": { "type": "number", "minimum": 0, "maximum": 1 }, "reason_code": { "$ref": "#/components/schemas/ReasonCode" } } }, "EvidenceQuality": { "type": "string", "enum": [ "SOURCE_BACKED", "PARTIAL", "INSUFFICIENT" ] }, "Capability": { "type": "string", "enum": [ "COMPANY_SEARCH", "COMPANY_LOOKUP", "COMPANY_VERIFY", "COMPANY_EVENTS", "REGISTERED_SIGNATORY_LOOKUP", "REGISTERED_SIGNATORY_VERIFY", "SANCTIONS_CHECK", "FINMA_CHECK", "FINMA_AUTHORISATION_CHECK", "FINMA_WARNING_CHECK", "VAT_VERIFY", "LEI_LOOKUP", "ADDRESS_VERIFY", "COUNTERPARTY_VERIFY", "TRANSACTION_VERIFY", "IBAN_PAYEE_VERIFY" ] }, "UnsupportedCapability": { "type": "object", "required": [ "supported", "capability", "reason_code", "alternatives" ], "properties": { "supported": { "type": "boolean", "enum": [ false ] }, "capability": { "type": "string" }, "reason_code": { "$ref": "#/components/schemas/ReasonCode" }, "alternatives": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } }, "message": { "type": "string" } } }, "CapabilityStatus": { "type": "object", "description": "Support and operational availability are distinct. `supported` states whether BUMIT implements the capability at all; `available` states whether this deployment can serve it right now. A capability BUMIT implements whose source is unconfigured is supported:true, available:false with reason_code SOURCE_NOT_CONFIGURED — it is never reported as unsupported.", "required": [ "capability", "supported", "available", "reason_code" ], "properties": { "capability": { "type": "string" }, "supported": { "type": "boolean" }, "available": { "type": "boolean" }, "reason_code": { "oneOf": [ { "$ref": "#/components/schemas/ReasonCode" }, { "type": "null" } ] }, "alternatives": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } }, "required_sources": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } } }, "LegalStatus": { "type": "string", "enum": [ "ACTIVE", "BEING_CANCELLED", "CANCELLED" ] }, "Provenance": { "type": "object", "required": [ "source", "observed_at" ], "properties": { "source": { "type": "string", "enum": [ "ZEFIX" ] }, "source_record_id": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "observed_at": { "type": "string", "format": "date-time" }, "source_hash": { "type": "string" }, "source_timestamp": { "type": [ "string", "null" ] } } }, "Freshness": { "type": "object", "required": [ "observed_at", "stale", "served_from_cache", "source_state", "upstream_status" ], "description": "Cached evidence is never reported as LIVE.", "properties": { "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "retrieved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Set only when this response came from a successful upstream call." }, "source_timestamp": { "type": [ "string", "null" ] }, "age_seconds": { "type": [ "integer", "null" ] }, "max_age_hours": { "type": [ "integer", "null" ] }, "stale": { "type": "boolean" }, "served_from_cache": { "type": "boolean" }, "source_state": { "$ref": "#/components/schemas/SourceState" }, "upstream_status": { "$ref": "#/components/schemas/UpstreamStatus" }, "reason_code": { "anyOf": [ { "$ref": "#/components/schemas/ReasonCode" }, { "type": "null" } ] } } }, "Address": { "type": "object", "properties": { "street": { "type": [ "string", "null" ] }, "house_number": { "type": [ "string", "null" ] }, "address_addon": { "type": [ "string", "null" ] }, "po_box": { "type": [ "string", "null" ] }, "postcode": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "canton": { "type": [ "string", "null" ] }, "country": { "type": "string" } } }, "Company": { "type": "object", "required": [ "legal_name", "normalized_name", "provenance", "not_provided_by_source" ], "properties": { "uid": { "type": [ "string", "null" ] }, "ehraid": { "type": [ "integer", "null" ] }, "chid": { "type": [ "string", "null" ] }, "legal_name": { "type": "string" }, "normalized_name": { "type": "string" }, "translations": { "type": "array", "items": { "type": "string" } }, "names": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "normalized_name": { "type": "string" }, "is_current": { "type": "boolean" }, "sequence_nr": { "type": [ "integer", "null" ] } } } }, "legal_form": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "integer", "null" ] }, "code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "short_name": { "type": [ "string", "null" ] } } }, "legal_status": { "$ref": "#/components/schemas/LegalStatus" }, "seat": { "type": [ "string", "null" ] }, "canton": { "type": [ "string", "null" ] }, "address": { "anyOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "null" } ] }, "purpose": { "type": [ "string", "null" ] }, "capital_nominal": { "type": [ "string", "null" ] }, "capital_currency": { "type": [ "string", "null" ] }, "incorporation_date": { "type": [ "string", "null" ], "description": "Not published by Zefix; always null in this phase." }, "deletion_date": { "type": [ "string", "null" ] }, "last_sogc_date": { "type": [ "string", "null" ] }, "people": { "type": "array", "items": { "type": "object" }, "description": "Not published by Zefix; empty in this phase." }, "relationships": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "uid": { "type": [ "string", "null" ] }, "ehraid": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] } } } }, "not_provided_by_source": { "type": "array", "items": { "type": "string" } }, "provenance": { "$ref": "#/components/schemas/Provenance" } } }, "Attribution": { "type": "object", "required": [ "source", "retrieved_at", "legal_effect", "guaranteed" ], "description": "Source attribution for Zefix-derived facts. Zefix data has no legal effect and is provided without guarantee.", "properties": { "source": { "type": "string", "enum": [ "ZEFIX" ] }, "source_label": { "type": "string" }, "source_reference": { "type": "string" }, "source_record_id": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "retrieved_at": { "type": "string", "format": "date-time" }, "source_timestamp": { "type": [ "string", "null" ] }, "legal_effect": { "type": "boolean", "enum": [ false ] }, "guaranteed": { "type": "boolean", "enum": [ false ] }, "notices": { "type": "array", "items": { "type": "string" } } } }, "DerivedValue": { "type": "object", "required": [ "field", "source", "source_value", "bumit_derived_value", "modified" ], "description": "A value BUMIT derived from Zefix data. Not a Zefix-published field.", "properties": { "field": { "type": "string" }, "source": { "type": "string", "enum": [ "ZEFIX" ] }, "source_value": {}, "bumit_derived_value": {}, "modified": { "type": "boolean", "enum": [ true ] }, "derivation": { "type": "string" } } }, "Disclaimer": { "type": "object", "required": [ "legal_effect", "source_guarantees_data", "statement" ], "properties": { "legal_effect": { "type": "boolean", "enum": [ false ] }, "source_guarantees_data": { "type": "boolean", "enum": [ false ] }, "bumit_derived_fields_present": { "type": "boolean" }, "statement": { "type": "string" }, "notices": { "type": "array", "items": { "type": "string" } } } }, "CompanyResult": { "type": "object", "required": [ "status", "company", "provenance", "freshness", "attribution", "disclaimer" ], "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "company": { "$ref": "#/components/schemas/Company" }, "provenance": { "$ref": "#/components/schemas/Provenance" }, "attribution": { "$ref": "#/components/schemas/Attribution" }, "bumit_derived_values": { "type": "array", "items": { "$ref": "#/components/schemas/DerivedValue" } }, "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "CompanySearchResult": { "type": "object", "required": [ "status", "query", "count", "results", "disclaimer" ], "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "query": { "type": "string" }, "source": { "type": "string", "enum": [ "ZEFIX" ] }, "served_from_cache": { "type": "boolean" }, "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "attribution": { "$ref": "#/components/schemas/Attribution" }, "bumit_derived_values": { "type": "array", "items": { "$ref": "#/components/schemas/DerivedValue" } } }, "additionalProperties": true } }, "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }, "coverage_note": { "type": "string" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "Coverage": { "type": "object", "required": [ "complete", "partial", "established", "not_covered", "profile_complete", "complete_kyb" ], "properties": { "complete": { "type": "boolean", "enum": [ false ] }, "partial": { "type": "boolean", "enum": [ true ] }, "established": { "type": "array", "items": { "type": "string" } }, "not_covered": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" }, "profile_id": { "type": "string" }, "profile_version": { "type": "string" }, "evaluation_context": { "type": "string", "enum": [ "PRODUCTION", "FIXTURE_TEST" ] }, "mandatory_required": { "type": "array", "items": { "type": "string" } }, "mandatory_completed": { "type": "array", "items": { "type": "string" } }, "mandatory_unresolved": { "type": "array", "items": { "type": "string" } }, "mandatory_not_applicable": { "type": "array", "items": { "type": "string" } }, "optional_requested": { "type": "array", "items": { "type": "string" } }, "optional_completed": { "type": "array", "items": { "type": "string" } }, "informational_requested": { "type": "array", "items": { "type": "string" } }, "informational_completed": { "type": "array", "items": { "type": "string" } }, "capabilities_unavailable": { "type": "array", "items": { "type": "string" } }, "sources_unavailable": { "type": "array", "items": { "type": "string" } }, "profile_complete": { "type": "boolean", "description": "True when every applicable mandatory check of the profile was resolved with usable evidence. Profile completeness is never complete KYB." }, "complete_kyb": { "type": "boolean", "enum": [ false ] } } }, "CheckResult": { "type": "object", "required": [ "check", "decision", "rationale" ], "properties": { "check": { "type": "string" }, "decision": { "$ref": "#/components/schemas/Decision" }, "rationale": { "type": "string" }, "sources": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "type": "object" } }, "stale": { "type": "boolean" }, "requirement": { "type": "string", "enum": [ "MANDATORY", "OPTIONAL", "INFORMATIONAL" ], "description": "Only MANDATORY checks determine the overall decision." }, "applicability": { "type": "string", "enum": [ "APPLICABLE", "NOT_APPLICABLE" ], "description": "NOT_APPLICABLE is never expressed as UNKNOWN." }, "reason_codes": { "type": "array", "items": { "$ref": "#/components/schemas/ReasonCode" } }, "evidence_class": { "type": "string", "enum": [ "SOURCE_EVIDENCE", "SYNTHETIC_FIXTURE", "NO_EVIDENCE" ], "description": "SYNTHETIC_FIXTURE evidence never satisfies a mandatory check in the PRODUCTION evaluation context." }, "source_state": { "$ref": "#/components/schemas/SourceState" }, "observed_state": { "type": "string", "description": "The source-specific state observed (for example CLEAR, VAT_ACTIVE, LEI_NOT_FOUND, OFFICIAL_ADDRESS). Source vocabularies are never collapsed into the company-level decision." } } }, "VerificationResult": { "type": "object", "required": [ "status", "verification_id", "uid", "decision", "decision_origin", "profile", "pass_semantics", "reason_codes", "ruleset_version", "coverage", "checks", "claims", "evidence_quality", "inference_used", "freshness", "upstream_status", "upstream_checked", "legal_effect", "disclaimer" ], "properties": { "status": { "type": "string", "enum": [ "OK" ] }, "verification_id": { "type": "string", "format": "uuid" }, "trace_id": { "type": [ "string", "null" ], "format": "uuid" }, "uid": { "type": "string" }, "uid_checksum_valid": { "type": "boolean" }, "decision": { "$ref": "#/components/schemas/Decision" }, "reason_codes": { "type": "array", "items": { "$ref": "#/components/schemas/ReasonCode" } }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } }, "evidence_quality": { "$ref": "#/components/schemas/EvidenceQuality" }, "inference_used": { "type": "boolean" }, "upstream_status": { "$ref": "#/components/schemas/UpstreamStatus" }, "upstream_checked": { "type": "boolean", "description": "True when this request actually attempted an upstream call. A cache-first answer served without contacting the source reports false, so a machine can tell an untouched fresh cache hit from a cached answer served after a failed refresh." }, "sources": { "type": "array", "items": { "type": "object", "required": [ "source", "upstream_status", "source_state" ], "properties": { "source": { "type": "string" }, "upstream_status": { "$ref": "#/components/schemas/UpstreamStatus" }, "source_state": { "$ref": "#/components/schemas/SourceState" }, "max_age_hours": { "type": [ "integer", "null" ] } } } }, "decision_origin": { "type": "string", "enum": [ "BUMIT_DERIVED" ], "description": "The decision is derived by BUMIT and is not a Zefix-published field." }, "profile": { "type": "object", "required": [ "profile_id", "profile_version", "ruleset_version", "mandatory_checks" ], "description": "The immutable, versioned verification profile whose mandatory checks produced the decision.", "properties": { "profile_id": { "type": "string" }, "profile_version": { "type": "string" }, "ruleset_version": { "type": "string" }, "evaluation_context": { "type": "string", "enum": [ "PRODUCTION", "FIXTURE_TEST" ] }, "mandatory_checks": { "type": "array", "items": { "type": "string" } }, "optional_checks": { "type": "array", "items": { "type": "string" } }, "informational_checks": { "type": "array", "items": { "type": "string" } }, "not_required": { "type": "array", "items": { "type": "string" } } } }, "pass_semantics": { "type": "object", "description": "Structural boundary of a PASS. Every flag is false: a PASS is never safe-to-transact, trustworthy, risk-free, solvent, legally approved, complete KYB, ownership-screened or signatory-confirmed.", "properties": { "meaning": { "type": "string" }, "legal_effect": { "type": "boolean", "enum": [ false ] }, "complete_kyb": { "type": "boolean", "enum": [ false ] }, "safe_to_transact": { "type": "boolean", "enum": [ false ] }, "weighted_score_used": { "type": "boolean", "enum": [ false ] }, "llm_used": { "type": "boolean", "enum": [ false ] } } }, "ruleset_version": { "type": "string" }, "legal_effect": { "type": "boolean", "enum": [ false ], "description": "Zefix-reported information carries no legal effect." }, "disclaimer": { "$ref": "#/components/schemas/Disclaimer" }, "attribution": { "anyOf": [ { "$ref": "#/components/schemas/Attribution" }, { "type": "null" } ] }, "bumit_derived_values": { "type": "array", "items": { "$ref": "#/components/schemas/DerivedValue" } }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "company": { "anyOf": [ { "$ref": "#/components/schemas/Company" }, { "type": "null" } ] }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CheckResult" } }, "provenance": { "anyOf": [ { "$ref": "#/components/schemas/Provenance" }, { "type": "null" } ] }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "unavailable_sources": { "type": "array", "items": { "type": "string" } }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "RegistryEventProvenance": { "type": "object", "required": [ "source", "source_record_id", "schema_version", "source_hash", "observed_at" ], "properties": { "source": { "const": "SHAB" }, "source_record_id": { "type": "string", "description": "Publication UUID as published by the source." }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "description": "SHAB XML schema version the payload declared, e.g. 1.26." }, "source_hash": { "type": "string", "description": "SHA-256 of the raw publication payload; the idempotency identity." }, "observed_at": { "type": "string", "format": "date-time" } } }, "RegistryEvent": { "type": "object", "required": [ "event_type", "uid", "company_link_status", "publication", "claims", "provenance" ], "properties": { "event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "event_type": { "type": "string", "enum": [ "REGISTRATION", "DELETION", "OTHER_HR_PUBLICATION", "UNCLASSIFIED" ] }, "classification_basis": { "type": "string" }, "uid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_link_status": { "type": "string", "enum": [ "LINKED", "UID_IDENTIFIED", "UNRESOLVED" ] }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publication": { "type": "object" }, "prior_publications": { "type": "array", "items": { "type": "object" } }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } }, "provenance": { "$ref": "#/components/schemas/RegistryEventProvenance" }, "attribution": { "type": "object" }, "legal_effect": { "const": false }, "describes_current_state": { "const": false } } }, "CompanyEventsResponse": { "type": "object", "required": [ "status", "uid", "source", "order", "count", "events", "coverage" ], "properties": { "status": { "const": "OK" }, "uid": { "type": "string" }, "uid_checksum_valid": { "type": "boolean" }, "source": { "const": "SHAB" }, "order": { "const": "PUBLICATION_DATE_DESC" }, "count": { "type": "integer" }, "limit": { "type": "integer" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/RegistryEvent" } }, "coverage": { "type": "object" }, "describes_current_state": { "const": false }, "signatory_authority_covered": { "const": false }, "inference_used": { "const": false }, "reason_codes": { "type": "array", "items": { "type": "string" } }, "legal_effect": { "const": false }, "disclaimer": { "type": "object" }, "meta": { "$ref": "#/components/schemas/Meta" } } }, "SanctionsCheckState": { "type": "string", "enum": [ "CLEAR", "POSSIBLE_MATCH", "CONFIRMED_MATCH", "UNKNOWN" ] }, "SanctionsCandidate": { "type": "object", "required": [ "target_ssid", "sanctions_set_ids", "listing_state", "matched_name", "match_basis" ], "properties": { "target_ssid": { "type": "string", "description": "SECO target SSID. SOURCE_FACT." }, "sanctions_set_ids": { "type": "array", "items": { "type": "string" }, "description": "Every sanctions set the target belongs to. Many-to-many, never collapsed." }, "program_ssids": { "type": "array", "items": { "type": "string" } }, "foreign_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "listing_state": { "type": "string", "enum": [ "LISTED", "DE_LISTED", "UNKNOWN" ] }, "listing_state_basis": { "type": "string" }, "latest_modification_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "matched_name": { "type": "object", "description": "The source-published name that matched, with BUMIT normalization keys reported separately from the source value." }, "match_basis": { "type": "array", "items": { "type": "string", "enum": [ "EXACT_NORMALIZED_NAME", "TOKEN_SET_EQUAL_NAME", "LEGAL_FORM_REDUCED_NAME" ] }, "description": "Deterministic rules that fired. No similarity score exists." }, "supporting_evidence": { "type": "object" } } }, "CompanySanctionsResponse": { "type": "object", "required": [ "status", "uid", "check_state", "scope", "coverage", "matching", "candidates" ], "properties": { "status": { "const": "OK" }, "uid": { "type": "string" }, "uid_checksum_valid": { "type": "boolean" }, "capability": { "const": "SANCTIONS_CHECK" }, "check_state": { "$ref": "#/components/schemas/SanctionsCheckState" }, "reason_codes": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "object", "properties": { "scope": { "const": "DIRECT_SECO_LIST_SCREENING" }, "direct_subjects_only": { "const": true }, "ownership_control_checked": { "const": false }, "natural_person_screening": { "const": false }, "transaction_screening": { "const": false } } }, "screened_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "normalized_screened_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "coverage": { "type": "object", "properties": { "complete": { "const": false }, "confirmed_match_reachable": { "const": false }, "live_ingestion_enabled": { "const": false }, "ingestion_mode": { "const": "FIXTURE_BASED" } } }, "matching": { "type": "object", "properties": { "engine": { "const": "DETERMINISTIC" }, "ruleset_version": { "type": "string" }, "name_normalization_ruleset_version": { "type": "string" }, "candidate_rules": { "type": "array", "items": { "type": "string" } }, "similarity_scoring_used": { "const": false }, "fuzzy_confirmation_possible": { "const": false }, "llm_used": { "const": false } } }, "candidate_count": { "type": "integer" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/SanctionsCandidate" } }, "freshness": { "$ref": "#/components/schemas/Freshness" }, "claims": { "type": "array", "items": { "$ref": "#/components/schemas/Claim" } }, "sources": { "type": "array", "items": { "const": "SECO_SANCTIONS" } }, "provenance": { "type": [ "object", "null" ] }, "attribution": { "type": [ "object", "null" ] }, "inference_used": { "const": false }, "ruleset_version": { "type": "string" }, "legal_effect": { "const": false }, "semantic_boundary": { "type": "string" }, "disclaimer": { "type": "object" }, "meta": { "$ref": "#/components/schemas/Meta" } } } } }, "x-sources": [ { "id": "ZEFIX", "label": "Zefix PublicREST API — Federal Registry of Commerce", "base_url": "https://www.zefix.admin.ch/ZefixPublicREST", "authentication": "HTTP Basic (Zefix-Credentials)", "max_age_hours": 24, "attribution_required": true, "legal_effect": false, "guarantees_data": false, "notices": [ "Zefix-reported information has no legal effect. It is registry-derived information retrieved from Zefix, not a legally certified, binding or guaranteed statement of legal status.", "Zefix does not guarantee the completeness, accuracy or availability of this data. Upstream information may be incomplete, delayed, unavailable or erroneous." ] }, { "id": "SHAB", "label": "SHAB / SOGC — Swiss Official Gazette of Commerce, Official Gazettes Portal", "base_url": "https://www.amtsblattportal.ch/api/v1", "authentication": "None observed for publication retrieval", "max_age_hours": 24, "attribution_required": true, "legal_effect": false, "guarantees_data": false, "live_ingestion_enabled": false, "ingestion_mode": "FIXTURE_BASED", "notices": [ "This is BUMIT output derived from SHAB/SOGC publication data. It is not an official publication, not an official gazette extract and not a legally binding excerpt. Only the publication on the Official Gazettes Portal is authoritative.", "The Official Gazettes Portal does not guarantee the completeness, accuracy, timeliness or availability of publication data. Publications may be corrected, superseded or republished.", "A publication records what was published at a point in time. It does not establish current company state, current representation rights or current signature authority." ] }, { "id": "SECO_SANCTIONS", "label": "SECO — State Secretariat for Economic Affairs, consolidated Swiss sanctions list", "base_url": "https://www.sesam.search.admin.ch", "authentication": "None observed for dataset download", "max_age_hours": 168, "attribution_required": true, "legal_effect": false, "guarantees_data": false, "live_ingestion_enabled": false, "ingestion_mode": "FIXTURE_BASED", "notices": [ "BUMIT screening output has no legal effect. It is not an official sanctions determination, not legal advice and not a compliance sign-off. Only the official SECO publication is authoritative.", "The source does not guarantee the completeness, accuracy, timeliness or availability of the sanctions dataset. Listings change, and locally stored data may lag the official list.", "SECO's list concerns directly sanctioned subjects. It establishes no ownership or control relationships, so a screening result says nothing about sanctioned owners, controllers or beneficial owners." ] }, { "id": "FINMA", "label": "FINMA — Swiss Financial Market Supervisory Authority", "base_url": "https://www.finma.ch", "authentication": "None observed for published list downloads", "max_age_hours": 168, "attribution_required": true, "legal_effect": false, "guarantees_data": false, "live_ingestion_enabled": false, "ingestion_mode": "FIXTURE_BASED", "notices": [ "BUMIT output has no legal effect. It is not a FINMA determination, not an authorisation confirmation, not legal advice and not a compliance sign-off. Only FINMA's own publication is authoritative.", "FINMA does not guarantee that its lists are exhaustive or current, and publishes no update cadence for them. A locally stored snapshot may lag the published list.", "BUMIT reports list membership, not legal authorisation. Absence from a list never proves the absence of authorisation, and presence never confirms an authorisation at this instant. Some entities are supervised by other bodies and some activities require no FINMA authorisation.", "A warning-list candidate is a name candidate only. FINMA states that its warning list is not exhaustive and not updated daily, and that an entry does not mean the activity is unlawful. BUMIT never converts an entry into illegality, fraud or sanctions.", "This deployment runs FINMA on synthetic fixtures. Real FINMA ingestion, recurring retrieval, commercial activation and raw-data redistribution are on hold pending FINMA's written clarification." ] }, { "id": "GLEIF", "label": "GLEIF — Global Legal Entity Identifier Foundation, Level 1 reference data", "base_url": "https://api.gleif.org/api/v1", "authentication": "None required for public LEI reference data", "max_age_hours": 168, "attribution_required": true, "legal_effect": false, "guarantees_data": false, "live_ingestion_enabled": false, "ingestion_mode": "FIXTURE_BASED", "http_caching_observed": { "etag_present": false, "last_modified_present": false, "rate_limit_headers_present": false, "note": "GLEIF suppresses HTTP caching and exposes no HTTP validators, so freshness is derived from payload fields only and never from an invented HTTP guarantee." }, "notices": [ "BUMIT output has no legal effect. It is not a GLEIF certification, not a confirmation of a company's existence or activity, not an authorisation, not legal advice and not a compliance sign-off. Only GLEIF's own publication is authoritative.", "GLEIF publishes two independent statuses: the entity status and the LEI registration status. BUMIT keeps them separate and verbatim. An ISSUED LEI does not mean the company is active, and a LAPSED or RETIRED LEI does not mean the company is inactive or does not exist.", "Linkage is deterministic identifier equality only: the GLEIF record must be registered under authority RA000548 and its registeredAs value must exactly equal the compact form of the queried canonical Swiss UID. No name, address, city, legal-form or fuzzy matching is used anywhere.", "NOT_FOUND is emitted only after a successful lookup against usable stored GLEIF data, and means only that no exactly matching record was present. A transport failure, disabled source, parse failure, malformed payload or unusable UID is always UNKNOWN.", "This deployment runs GLEIF on synthetic fixtures. No GLEIF production integration is active: live retrieval, Golden Copy downloads, delta synchronisation and scheduled ingestion are not implemented." ] }, { "id": "UID_VAT", "label": "Swiss Federal Statistical Office (FSO/BFS) — UID register, Public Services webservice 5.0", "base_url": null, "transport": "SOAP", "operations": [ "GET_BY_UID", "VALIDATE_UID", "VALIDATE_VAT_NUMBER" ], "authentication": "None required for the public services", "max_age_hours": 72, "attribution_required": true, "legal_effect": false, "guarantees_data": false, "live_ingestion_enabled": false, "ingestion_mode": "FIXTURE_BASED", "rate_limit_documented": false, "note": "No rate limit, cache validator or freshness guarantee is asserted for this source. A future live path must be cache-first, concurrency-bounded and must honour upstream rate-limit signals; none of that transport behaviour exists yet.", "notices": [ "BUMIT output has no legal effect. It is not a certification by the Federal Statistical Office, not a VAT clearance, not tax advice, not a confirmation that a company exists or is operating, and not a compliance sign-off. Only the official register publication is authoritative.", "UID assignment, entity status and VAT registration state are three separate questions. BUMIT keeps them separate and verbatim. A structurally valid or assigned UID does not mean the company is active, and an active VAT registration does not mean the company is active, solvent or safe to transact with.", "The UID register may associate an entity with a VAT UID that differs from its company UID, including branch and VAT-group structures. BUMIT retains both identifiers independently as source facts, reports any canonical form separately as a normalized value, and never constructs a VAT status from a company UID alone.", "The normalized VAT result comes from an explicitly versioned mapping of source status values. A source status the mapping does not list — including an unknown or future value — yields UNKNOWN and is never silently mapped to active or inactive. The source value itself is always reported verbatim alongside the normalized result.", "Absence of evidence is never evidence of absence. NO_VAT_REGISTRATION requires the source to explicitly state that no registration exists. A missing record, silent VAT block, malformed payload, stale dataset, unavailable source or contradictory evidence is UNKNOWN.", "This deployment runs the UID register source on synthetic fixtures. No production integration is active: live SOAP retrieval, scheduled ingestion and polling are not implemented." ] }, { "id": "SWISSTOPO", "label": "Federal Office of Topography swisstopo — Official Directory of Building Addresses", "base_url": null, "transport": "HTTPS complete-dataset download (not implemented)", "operations": [ "COMPLETE_DATASET_DOWNLOAD" ], "authentication": "None documented for the published directory", "max_age_hours": 720, "attribution_required": true, "legal_effect": false, "guarantees_data": false, "live_ingestion_enabled": false, "ingestion_mode": "FIXTURE_BASED", "rate_limit_documented": false, "note": "No rate limit, cache validator or freshness guarantee is asserted for this source. A future live path must download the complete dataset on a governed schedule, stage it, validate it and only then activate it; none of that transport behaviour exists yet.", "layer_reference": "ch.swisstopo.amtliches-gebaeudeadressverzeichnis", "notices": [ "BUMIT output has no legal effect. It is not a certification by swisstopo, not a domicile confirmation, not a deliverability guarantee and not a compliance sign-off. Only the official swisstopo publication is authoritative.", "ADDRESS_VERIFY establishes correspondence with the official Swiss building-address directory only. It does not establish that a company is registered, domiciled or operating at the address, that mail is deliverable there, that any company is active, or that a transaction is safe. No company register address is compared in this phase.", "ADR_STATUS (planned / real / outdated) and ADR_OFFICIAL (a boolean) are two separate source fields. BUMIT reports both verbatim and never collapses one into the other: a real status alone does not make an address official, and an official flag never erases the published status.", "ADR_EGAID (building address), BDG_EGID (building), ADR_EDID (entrance), STR_ESID (street) and COM_FOSNR (municipality) are five separate federal identifiers. BUMIT retains each independently and verbatim, never derives one from another and never manufactures one.", "The normalized address result comes from an explicitly versioned mapping of the source ADR_STATUS value together with the separate ADR_OFFICIAL boolean. ADR_STATUS and ADR_OFFICIAL are never collapsed: a real status alone does not make an address official, and an official flag never erases the published status. A status the mapping does not list — including an unknown or future value — yields UNKNOWN and is never silently mapped.", "Matching is deterministic exact equality on normalized address components: street label, house number, postcode and locality. Normalization is formatting only — Unicode NFC, whitespace, comparison-case, canonical four-digit postcode and conservative house-number formatting. A multilingual street label is preserved whole and additionally exposes exact per-language segment keys. No fuzzy matching, edit distance, similarity score, embedding, LLM, address guessing or nearest-geographic selection exists in this path, and several matches are reported as MULTIPLE_MATCHES rather than resolved.", "Absence of evidence is never evidence of absence. NOT_FOUND is emitted only after a deterministic lookup against a usable, sufficiently current dataset, and means only that no entry matched in the data BUMIT checked. A missing, malformed, stale, contradictory or unavailable dataset is UNKNOWN.", "This deployment runs the swisstopo source on synthetic fixtures. No production integration is active: live download, STAC, REST and SPARQL retrieval, scheduled ingestion and polling are not implemented." ] } ], "x-lei-lookup": { "source": "GLEIF", "capability": "LEI_LOOKUP", "capability_operationally_available": false, "ruleset_version": "0.6.0-phase6", "scope": { "scope": "GLEIF_LEVEL1_REGISTRATION_IDENTIFIER_LOOKUP", "linkage": "EXACT_REGISTRATION_AUTHORITY_IDENTIFIER", "name_matching_used": false, "address_matching_used": false, "city_matching_used": false, "legal_form_matching_used": false, "fuzzy_matching_used": false, "scoring_used": false, "llm_used": false, "automatic_duplicate_resolution": false, "entity_and_registration_status_separated": true, "ownership_control_checked": false, "beneficial_ownership_checked": false, "establishes_transaction_safety": false, "level2_parent_engine_implemented": false }, "results": [ "FOUND", "NOT_FOUND", "MULTIPLE_RECORDS", "UNKNOWN" ], "linkage": { "method": "EXACT_REGISTRATION_AUTHORITY_IDENTIFIER", "registration_authority": "RA000548", "requires_exact_registered_as": true, "validation_authority_required": false, "name_matching_used": false, "address_matching_used": false, "fuzzy_matching_used": false, "llm_used": false, "uid_format_note": "GLEIF publishes the Swiss commercial-register identifier compact, without the CHE- dash and without dot separators (for example CHE102753938), while the BUMIT canonical form is CHE-102.753.938. BUMIT applies a deterministic formatting transform on the QUERY side only. The GLEIF value is retained verbatim as a source fact and is never rewritten; any canonical UID stored alongside it is explicitly a normalized indexing value." }, "statuses": { "entity_status": "GLEIF entity status, verbatim and independent of the LEI registration status.", "registration_status": "GLEIF LEI registration status, verbatim and independent of the entity status. Unknown or future values are preserved, never mapped.", "collapsed_into_single_status": false }, "multiple_records_retained": true, "automatic_duplicate_resolution": false, "duplicate_note": "BUMIT does not assume that a Swiss UID maps to exactly one LEI. When more than one exact record matches, every record is returned and none is selected: no resolution is made on registration status, dates, name similarity or ordering. Duplicate and successor resolution requires documented GLEIF source semantics and a separate review.", "level2": { "parent_engine_implemented": false, "accounting_parent_is_beneficial_owner": false, "reporting_exception_means_no_parent": false, "exception_id_parsed": false, "note": "GLEIF Level 2 exposes accounting-consolidation relationships and reporting exceptions. A GLEIF accounting consolidating parent is NOT a beneficial owner, NOT a UBO and NOT a controlling natural person, and a reporting exception such as NO_KNOWN_PERSON is NOT NO_PARENT, NOT NO_OWNER and NOT NO_UBO. No Level 2 parent engine is implemented; where exception structures are retained, the source category, reason and the whole opaque exception id are stored verbatim." }, "absence_semantics": "NOT_FOUND is emitted only after a successful lookup against usable stored data. A transport failure, disabled source, parse failure, malformed payload, stale dataset or unusable UID is always UNKNOWN, never NOT_FOUND, and NOT_FOUND never means the company does not exist.", "provenance": "Every record carries source GLEIF, the LEI as source record identifier, a source reference, BUMIT's retrieved_at, the payload hash, the ingestion id and GLEIF's own update dates. registration.lastUpdateDate is a source field and is never treated as BUMIT's retrieval time; meta.goldenCopy.publishDate is retained only where GLEIF supplied it and is never a sole cache validator.", "not_covered": [ "COMPANY_EXISTENCE_DETERMINATION", "COMPANY_ACTIVE_STATE_DETERMINATION", "TRANSACTION_SAFETY", "OWNERSHIP_OR_CONTROL_ANALYSIS", "BENEFICIAL_OWNERSHIP_OR_UBO", "LEVEL2_PARENT_RELATIONSHIP_ENGINE", "DUPLICATE_OR_SUCCESSOR_LEI_RESOLUTION", "NAME_OR_ADDRESS_BASED_LINKAGE", "NON_SWISS_REGISTRATION_AUTHORITY_LINKAGE", "GLOBAL_UID_TO_LEI_UNIQUENESS", "LEGAL_CERTIFICATION" ], "semantic_boundary": "FOUND means only that a GLEIF Level 1 record exists whose Swiss commercial-register identifier exactly equals the queried canonical UID under registration authority RA000548. It does not mean the company is active, solvent, authorised, compliant or safe to transact with. NOT_FOUND means only that no such exact record existed in the GLEIF data BUMIT holds; it never means the company does not exist, and it is only ever emitted after a successful lookup against usable source data. MULTIPLE_RECORDS means several exact records exist and BUMIT deliberately resolves none of them. UNKNOWN means the lookup could not be completed and is never a negative finding.", "semantic_boundaries": [ "ENTITY_STATUS_IS_NOT_LEI_REGISTRATION_STATUS", "LEI_ISSUED_IS_NOT_COMPANY_ACTIVE", "LEI_LAPSED_IS_NOT_COMPANY_INACTIVE", "LEI_LAPSED_IS_NOT_COMPANY_DOES_NOT_EXIST", "LEI_RETIRED_HAS_ONLY_ITS_DOCUMENTED_GLEIF_MEANING", "LEI_FOUND_IS_NOT_SAFE_TO_TRANSACT", "LEI_NOT_FOUND_IS_NOT_COMPANY_DOES_NOT_EXIST", "LEI_RECORD_IS_NOT_A_LEGAL_CERTIFICATION", "ACCOUNTING_CONSOLIDATION_PARENT_IS_NOT_BENEFICIAL_OWNER", "REPORTING_EXCEPTION_IS_NOT_ABSENCE_OF_PARENT_OR_OWNER" ], "live_retrieval_enabled": false, "ingestion_mode": "FIXTURE_BASED", "evidence_class": "SYNTHETIC_FIXTURE", "inferred_claims_produced": false, "legal_effect": false }, "x-vat-verification": { "source": "UID_VAT", "capability": "VAT_VERIFY", "capability_operationally_available": false, "ruleset_version": "0.7.0-phase7", "status_mapping_version": "uid-vat-status-map-1", "supported_source_statuses": [ "ACTIVE", "INACTIVE", "DELETED", "LIQUIDATED" ], "scope": { "scope": "SWISS_UID_REGISTER_VAT_STATE_RETRIEVAL", "linkage": "EXACT_CANONICAL_UID_EQUALITY", "direct_subject_only": true, "company_uid_assumed_equal_to_vat_uid": false, "name_matching_used": false, "address_matching_used": false, "fuzzy_matching_used": false, "scoring_used": false, "llm_used": false, "entity_status_and_vat_status_separated": true, "establishes_company_existence": false, "establishes_company_activity": false, "establishes_transaction_safety": false, "sanctions_checked": false, "ownership_control_checked": false }, "results": [ "VAT_ACTIVE", "VAT_INACTIVE", "NO_VAT_REGISTRATION", "UNKNOWN" ], "linkage": { "method": "EXACT_CANONICAL_UID_EQUALITY", "company_uid_assumed_equal_to_vat_uid": false, "name_matching_used": false, "address_matching_used": false, "fuzzy_matching_used": false, "llm_used": false, "automatic_record_selection": false, "uid_relationship_note": "The UID register may associate an entity with a VAT UID that differs from its company UID, including branch and VAT-group structures. BUMIT retains both identifiers independently as source facts, reports any canonical form separately as a normalized value, and never constructs a VAT status from a company UID alone." }, "statuses": { "uid_assignment": "What the source says about UID assignment. Never an entity operational status and never a VAT state.", "entity_status": "Source entity status, verbatim and independent of every VAT field.", "vat_status": "Source VAT status, verbatim and independent of the entity status. Unknown or future values are preserved, never mapped.", "collapsed_into_single_status": false, "mapping_note": "The normalized VAT result comes from an explicitly versioned mapping of source status values. A source status the mapping does not list — including an unknown or future value — yields UNKNOWN and is never silently mapped to active or inactive. The source value itself is always reported verbatim alongside the normalized result." }, "absence_semantics": "Absence of evidence is never evidence of absence. NO_VAT_REGISTRATION requires the source to explicitly state that no registration exists. A missing record, silent VAT block, malformed payload, stale dataset, unavailable source or contradictory evidence is UNKNOWN.", "provenance": "Every record carries source UID_VAT, the source reference, BUMIT's retrieved_at, the payload hash and the ingestion id. Source VAT entry and end dates are source fields and are never treated as BUMIT's retrieval time.", "not_covered": [ "COMPANY_EXISTENCE_DETERMINATION", "COMPANY_ACTIVE_STATE_DETERMINATION", "TRANSACTION_SAFETY", "SANCTIONS_OR_REGULATORY_CLEARANCE", "OWNERSHIP_OR_CONTROL_ANALYSIS", "VAT_GROUP_STRUCTURE_INTERPRETATION", "HEAD_OFFICE_BRANCH_STRUCTURE_INTERPRETATION", "VAT_LIABILITY_OR_TAX_ADVICE", "NAME_OR_ADDRESS_BASED_LINKAGE", "LEGAL_CERTIFICATION" ], "semantic_boundary": "VAT_ACTIVE means only that the UID register record BUMIT holds carries a VAT status that an explicitly versioned mapping recognises as an active registration. It does not mean the company exists, is operating, is solvent, is authorised, is free of sanctions or is safe to transact with. VAT_INACTIVE describes the VAT registration only and never the company. NO_VAT_REGISTRATION is emitted only where the source explicitly establishes the absence of a registration, and never means the company does not exist or was not found. UNKNOWN means the question could not be answered from usable evidence and is never a negative finding.", "semantic_boundaries": [ "VALID_UID_IS_NOT_ACTIVE_COMPANY", "UID_ASSIGNED_IS_NOT_ACTIVE_COMPANY", "VALID_UID_IS_NOT_VAT_ACTIVE", "VAT_ACTIVE_IS_NOT_SAFE_TO_TRANSACT", "VAT_ACTIVE_IS_NOT_SANCTIONS_CLEARED", "VAT_INACTIVE_IS_NOT_COMPANY_INACTIVE", "VAT_INACTIVE_IS_NOT_COMPANY_DOES_NOT_EXIST", "NO_VAT_REGISTRATION_IS_NOT_COMPANY_NOT_FOUND", "INACTIVE_COMPANY_IS_NOT_INVALID_UID", "COMPANY_UID_IS_NOT_NECESSARILY_VAT_UID", "VAT_UID_IS_NOT_A_CONTROL_OR_OWNERSHIP_STATEMENT", "ENTITY_STATUS_IS_NOT_VAT_STATUS", "VAT_RECORD_IS_NOT_A_LEGAL_CERTIFICATION" ], "live_retrieval_enabled": false, "ingestion_mode": "FIXTURE_BASED", "evidence_class": "SYNTHETIC_FIXTURE", "inferred_claims_produced": false, "legal_effect": false }, "x-address-verification": { "source": "SWISSTOPO", "capability": "ADDRESS_VERIFY", "capability_operationally_available": false, "ruleset_version": "0.8.0-phase8", "status_mapping_version": "swisstopo-address-status-map-1", "normalization_version": "swisstopo-address-normalization-1", "normalization_rules": [ "UNICODE_NFC", "WHITESPACE_COLLAPSE", "CASE_FOLD_FOR_COMPARISON_ONLY", "CANONICAL_FOUR_DIGIT_POSTCODE", "CONSERVATIVE_HOUSE_NUMBER_FORMATTING", "MULTILINGUAL_LABEL_SEGMENT_PRESERVATION" ], "supported_source_statuses": [ "planned", "real", "outdated" ], "scope": { "scope": "OFFICIAL_SWISS_BUILDING_ADDRESS_DIRECTORY_CORRESPONDENCE", "linkage": "DETERMINISTIC_EXACT_NORMALIZED_ADDRESS_COMPONENT_EQUALITY", "company_linkage_checked": false, "company_register_address_compared": false, "establishes_company_domicile": false, "establishes_company_occupancy": false, "establishes_company_activity": false, "establishes_mail_deliverability": false, "establishes_transaction_safety": false, "fuzzy_matching_used": false, "edit_distance_used": false, "scoring_used": false, "embeddings_used": false, "llm_used": false, "geographic_nearest_match_used": false, "address_guessing_used": false, "automatic_match_selection": false }, "results": [ "OFFICIAL_ADDRESS", "PLANNED_ADDRESS", "OUTDATED_ADDRESS", "NOT_FOUND", "MULTIPLE_MATCHES", "UNKNOWN" ], "architecture": { "mode": "COMPLETE_DATASET_INGESTION_THEN_LOCAL_INDEX", "request_per_verification": false, "note": "Verification always reads a staged local index built from a complete dataset snapshot. No upstream request is ever made while answering a verification." }, "matching": { "method": "DETERMINISTIC_EXACT_NORMALIZED_ADDRESS_COMPONENT_EQUALITY", "fuzzy_matching_used": false, "similarity_scoring_used": false, "geographic_guessing_used": false, "llm_used": false, "automatic_record_selection": false, "matching_note": "Matching is deterministic exact equality on normalized address components: street label, house number, postcode and locality. Normalization is formatting only — Unicode NFC, whitespace, comparison-case, canonical four-digit postcode and conservative house-number formatting. A multilingual street label is preserved whole and additionally exposes exact per-language segment keys. No fuzzy matching, edit distance, similarity score, embedding, LLM, address guessing or nearest-geographic selection exists in this path, and several matches are reported as MULTIPLE_MATCHES rather than resolved." }, "statuses": { "adr_status": "Source lifecycle status (planned / real / outdated), verbatim. Never merged with the official flag.", "adr_official": "Separate source boolean. Absent or unparseable values stay null and never default to true or false.", "collapsed_into_single_status": false, "mapping_note": "The normalized address result comes from an explicitly versioned mapping of the source ADR_STATUS value together with the separate ADR_OFFICIAL boolean. ADR_STATUS and ADR_OFFICIAL are never collapsed: a real status alone does not make an address official, and an official flag never erases the published status. A status the mapping does not list — including an unknown or future value — yields UNKNOWN and is never silently mapped." }, "identifiers": { "preserved_independently": [ "ADR_EGAID", "BDG_EGID", "ADR_EDID", "STR_ESID", "COM_FOSNR" ], "note": "ADR_EGAID (building address), BDG_EGID (building), ADR_EDID (entrance), STR_ESID (street) and COM_FOSNR (municipality) are five separate federal identifiers. BUMIT retains each independently and verbatim, never derives one from another and never manufactures one." }, "absence_semantics": "Absence of evidence is never evidence of absence. NOT_FOUND is emitted only after a deterministic lookup against a usable, sufficiently current dataset, and means only that no entry matched in the data BUMIT checked. A missing, malformed, stale, contradictory or unavailable dataset is UNKNOWN.", "provenance": "Every record carries source SWISSTOPO, the source reference, BUMIT's retrieved_at, the payload hash and the ingestion id. Source modification and publication dates are source fields and are never treated as BUMIT's retrieval time.", "not_covered": [ "COMPANY_DOMICILE_DETERMINATION", "COMPANY_OCCUPANCY_DETERMINATION", "COMPANY_REGISTER_ADDRESS_COMPARISON", "MAIL_DELIVERABILITY", "GEOCODING_OR_NEAREST_ADDRESS_RESOLUTION", "BUILDING_EXISTENCE_OR_CONSTRUCTION_STATE", "RESIDENT_OR_TENANT_IDENTIFICATION", "TRANSACTION_SAFETY", "LEGAL_CERTIFICATION" ], "semantic_boundary": "OFFICIAL_ADDRESS means only that the queried address components correspond exactly to an entry in the official Swiss building-address directory snapshot BUMIT holds, and that the source marks that entry as a real, official address. It does not mean a company is registered, domiciled, operating or reachable there, that mail is deliverable, that any company is active, or that a transaction is safe. UNKNOWN means the question could not be answered from usable evidence and is never a negative finding.", "semantic_boundaries": [ "OFFICIAL_ADDRESS_IS_NOT_COMPANY_REGISTERED_AT_ADDRESS", "OFFICIAL_ADDRESS_IS_NOT_COMPANY_OPERATING_AT_ADDRESS", "OFFICIAL_ADDRESS_IS_NOT_MAIL_DELIVERABLE", "OFFICIAL_ADDRESS_IS_NOT_COMPANY_ACTIVE", "OFFICIAL_ADDRESS_IS_NOT_SAFE_TO_TRANSACT", "ADR_STATUS_IS_NOT_ADR_OFFICIAL", "ADR_OFFICIAL_DOES_NOT_REPLACE_ADR_STATUS", "REAL_STATUS_IS_NOT_OFFICIAL_FLAG", "PLANNED_ADDRESS_IS_NOT_A_NON_EXISTENT_BUILDING", "OUTDATED_ADDRESS_IS_NOT_A_DEMOLISHED_BUILDING", "NOT_FOUND_IS_NOT_ADDRESS_DOES_NOT_EXIST", "ADR_EGAID_IS_NOT_BDG_EGID_IS_NOT_ADR_EDID", "ADDRESS_RECORD_IS_NOT_A_LEGAL_CERTIFICATION" ], "live_retrieval_enabled": false, "ingestion_mode": "FIXTURE_BASED", "evidence_class": "SYNTHETIC_FIXTURE", "inferred_claims_produced": false, "legal_effect": false }, "x-source-usage": { "ZEFIX": { "attribution": "Every Zefix-derived fact carries source: ZEFIX, a retrieval timestamp, the source record identifier where available, and an official-source reference.", "derived_fields": "Normalized names, mapped status enums, freshness flags and PASS/REVIEW/FAIL/UNKNOWN decisions are BUMIT-derived and are reported separately from Zefix-published values.", "legal_effect": "Zefix-reported information has no legal effect and is not legally certified or binding.", "guarantee": "Zefix does not guarantee completeness, accuracy or availability. Upstream data may be incomplete, delayed, unavailable or erroneous.", "request_behaviour": "Cache-first. Locally stored data within the configured freshness window is reused; upstream requests are de-duplicated, concurrency-limited, spaced, retried with exponential backoff and jitter, bounded by a rolling request ceiling and interrupted by a circuit breaker.", "freshness": "Responses expose observed_at, source_timestamp, max_age_hours, stale and served_from_cache." }, "SHAB": { "attribution": "Every SHAB-derived event carries source: SHAB, the publication UUID, the publication number where available, a source reference to the Official Gazettes Portal, the declared schema version and an observation timestamp.", "derived_fields": "Parsing, canonical UID normalization, deterministic event classification, ordering and provenance are BUMIT-derived and are never presented as source-published fields.", "legal_effect": "BUMIT output is not an official publication and has no legal effect. Only the publication on the Official Gazettes Portal is authoritative.", "guarantee": "The source does not guarantee completeness, accuracy, timeliness or availability. Publications may be corrected, superseded or republished.", "request_behaviour": "Live and scheduled ingestion is disabled: no scheduler, no polling, no crawling and no bulk harvesting exists. Optional single-publication retrieval is gated behind explicit configuration.", "scope": "Historical publication evidence only. SHAB is not a current-state source and is never used for persons, functions or signature authority.", "schema_versions": "Only declared, supported SHAB schema versions are parsed. An undeclared or unsupported version is rejected and never parsed as a known version." }, "SECO_SANCTIONS": { "attribution": "Every sanctions result carries source: SECO_SANCTIONS, the published list type and source date, the retrieval timestamp, the SHA-256 dataset hash, the BUMIT ingestion id and the candidate target SSIDs, sanction-set ids and programme ids.", "derived_fields": "Name assembly from source parts, normalization keys, candidate generation, current listing state, the check state and the matching ruleset version are BUMIT-derived and are never presented as SECO assertions. swiss-sanctions-list/@date is the date the source publishes, not a dataset version or generation timestamp; SECO exposes neither.", "legal_effect": "BUMIT screening output has no legal effect. It is not an official sanctions determination, not legal advice and not a compliance sign-off.", "guarantee": "The source does not guarantee completeness, accuracy, timeliness or availability. Listings change and locally stored data may lag the official list.", "request_behaviour": "Live and scheduled ingestion is disabled: no scheduler, no polling, no background refresh, no crawling and no redistribution of the dataset exists. A single controlled download is gated behind explicit configuration, pending clarification of the dataset usage category with SECO.", "scope": "Direct entity screening only. Individual and object targets are never ingested, no natural-person screening data is stored, and no ownership, control or beneficial-ownership relationship is evaluated.", "free_text_boundary": "Registration numbers, tax identification numbers, IMO numbers, places of registration and entity types appearing in SECO free text are retained as source evidence only. They are never parsed into structured identifiers and no Swiss UID linkage to Zefix is inferred from them." }, "FINMA": { "attribution": "Every FINMA result carries source: FINMA, the source dataset identifier, a source reference, the BUMIT retrieval timestamp, the payload Last-Modified where available, the SHA-256 payload hash, the BUMIT ingestion id and the source record ordinal. Retrieval timestamps are always kept separate from source timestamps.", "derived_fields": "UID canonicalization and name normalization are deterministic BUMIT transformations; list membership, warning candidates, candidate ordering and the ruleset version are BUMIT-derived. FINMA's published names, cities, authorisation categories and warning dates are source facts and are never altered. No BUMIT value is presented as a FINMA determination.", "legal_effect": "BUMIT output has no legal effect, is not a FINMA determination, not an authorisation confirmation, not legal advice and not a compliance sign-off. The FINMA logo is never used and raw FINMA records are never redistributed.", "guarantee": "FINMA does not guarantee that its lists are exhaustive or current and publishes no update cadence. The warning list is explicitly neither exhaustive nor updated daily. A stored snapshot may lag the published list.", "request_behaviour": "No retrieval implementation exists: no fetch, no scheduler, no polling, no crawling, no background refresh and no redistribution. The gate always refuses — DISABLED without the explicit flag and NOT_IMPLEMENTED with it — pending FINMA's written clarification on automated retrieval, local storage and commercial derived verification.", "scope": "Two separate capabilities. Authorisation-list membership is keyed on canonical Swiss UID equality only. Warning-list screening produces exact normalized-name candidates only, never a confirmed identity. Natural persons, insurance-intermediary register data, authorisation withdrawals and permitted-activity scope are out of scope.", "date_semantics": "FINMA does not document what the warning-list Date means. It is stored verbatim as source_date_value with source_date_dimension: UNKNOWN, never renamed to a warning, publication or effective date, and never used for ordering or state derivation.", "absence_semantics": "An entry disappearing from a later dataset never implies withdrawal, revocation or removal, and absence from a list never proves the absence of authorisation or of regulatory concern." } }, "x-registry-events": { "source": "SHAB", "event_types": [ "REGISTRATION", "DELETION", "OTHER_HR_PUBLICATION", "UNCLASSIFIED" ], "classification": "Deterministic, from structured publication elements only. Publication prose is never interpreted.", "not_covered": [ "CURRENT_COMPANY_STATE", "CURRENT_SIGNATORY_AUTHORITY", "REGISTERED_PERSONS", "APPOINTMENTS_AND_REMOVALS", "SEMANTIC_CHANGE_EVENTS", "PUBLICATION_TEXT_INTERPRETATION", "COMPLETE_PUBLICATION_HISTORY" ], "live_ingestion_enabled": false, "ingestion_mode": "FIXTURE_BASED" }, "x-sanctions-screening": { "source": "SECO_SANCTIONS", "scope": { "scope": "DIRECT_SECO_LIST_SCREENING", "direct_subjects_only": true, "ownership_control_checked": false, "target_kinds_screened": [ "ENTITY" ], "natural_person_screening": false, "transaction_screening": false }, "check_states": [ "CLEAR", "POSSIBLE_MATCH", "CONFIRMED_MATCH", "UNKNOWN" ], "candidate_rules": [ "EXACT_NORMALIZED_NAME", "TOKEN_SET_EQUAL_NAME", "LEGAL_FORM_REDUCED_NAME" ], "confirmed_match_reachable": false, "confirmed_match_note": "CONFIRMED_MATCH is declared but unreachable. SECO publishes no structured company identifier, so no high-specificity authoritative identity rule exists for entity screening; fuzzy or exact name evidence alone must never confirm a sanctions match.", "similarity_scoring_used": false, "llm_used": false, "not_covered": [ "OWNERSHIP_OR_CONTROL_RELATIONSHIPS", "BENEFICIAL_OWNERSHIP", "NATURAL_PERSON_SCREENING", "TRANSACTION_SCREENING", "NON_SECO_SANCTIONS_REGIMES", "GLOBAL_SANCTIONS_CLEARANCE", "SANCTIONS_LEGAL_ADVICE" ], "semantic_boundary": "A result of CLEAR means only that no direct candidate match was found in the SECO dataset BUMIT checked. It does not mean the company is not sanctioned, that no sanctioned party owns or controls it, or that it is safe to transact with.", "target_kinds_screened": [ "ENTITY" ], "listing_state": "DERIVED from structured modification history. Presence in the whole list is never treated as current listing.", "zefix_join": "No authoritative identifier join exists between Zefix UIDs and SECO entity targets. Screening is candidate matching on names; no UID mapping is manufactured and name similarity never establishes identity.", "live_ingestion_enabled": false, "ingestion_mode": "FIXTURE_BASED", "legal_effect": false }, "x-finma-checks": { "source": "FINMA", "capabilities_independent": true, "combined_finma_status_emitted": false, "ruleset_version": "0.5.0-phase5", "legal_effect": false, "live_ingestion_enabled": false, "ingestion_mode": "FIXTURE_BASED", "evidence_class": "SYNTHETIC_FIXTURE", "authorisation": { "capability": "FINMA_AUTHORISATION_CHECK", "scope": { "scope": "FINMA_AUTHORISATION_LIST_MEMBERSHIP", "linkage": "CANONICAL_UID_EXACT_EQUALITY", "name_matching_used": false, "city_matching_used": false, "fuzzy_matching_used": false, "llm_used": false, "determines_legal_authorisation": false, "source_is_snapshot": true, "natural_person_screening": false }, "membership_states": [ "FOUND_IN_FINMA_LIST", "NOT_FOUND_IN_FINMA_LIST", "UNKNOWN" ], "linkage": "Exact canonical Swiss UID equality only. No name, city, branch, commercial-register, fuzzy or LLM inference.", "multiple_category_rows_preserved": true, "legal_conclusion_emitted": false, "not_covered": [ "LEGAL_AUTHORISATION_DETERMINATION", "PERMITTED_ACTIVITY_SCOPE", "AUTHORISATION_WITHDRAWAL_OR_REVOCATION", "SUPERVISION_BY_OTHER_BODIES", "INSURANCE_INTERMEDIARY_REGISTER", "NATURAL_PERSON_AUTHORISATION", "NAME_BASED_LIST_MEMBERSHIP" ], "semantic_boundary": "FOUND_IN_FINMA_LIST means only that the canonical UID appears in the FINMA authorisation-list snapshot BUMIT holds. It does not mean FINMA confirms an authorisation at this instant, and it does not describe which activities are permitted. NOT_FOUND_IN_FINMA_LIST means only that the UID was not present in that snapshot; it never means the company is not authorised, unlicensed or non-compliant. FINMA itself warns about the currency and completeness of its lists." }, "warning": { "capability": "FINMA_WARNING_CHECK", "scope": { "scope": "FINMA_WARNING_LIST_NAME_CANDIDATES", "linkage": "EXACT_NORMALIZED_NAME", "authoritative_identifier_available": false, "identity_confirmation_possible": false, "jurisdiction_confirms_identity": false, "fuzzy_matching_used": false, "scoring_used": false, "llm_used": false, "natural_person_screening": false, "company_subjects_only": true, "unknown_subject_entries_screened": false, "subject_type_inferred": false }, "results": [ "NO_DIRECT_LIST_MATCH", "POSSIBLE_LIST_MATCH", "UNKNOWN" ], "candidate_rules": [ "EXACT_NORMALIZED_NAME" ], "confirmed_match_supported": false, "confirmed_match_note": "No confirmed state exists. FINMA publishes no authoritative identifier for warning entries, so exact normalized-name equality can yield at most POSSIBLE_LIST_MATCH, and the commercial-register text is supporting evidence only.", "natural_person_entries_ingested": false, "company_subjects_only": true, "unknown_subject_entries_screened": false, "subject_type_note": "FINMA's published warning-list view, as observed during Phase 5 reconnaissance, does not expose a structured company/natural-person subject type. Company-only warning screening therefore remains limited until an authoritative way to distinguish companies from natural persons exists. BUMIT reports this as unsupported coverage rather than inferring entity type.", "similarity_scoring_used": false, "llm_used": false, "date_semantics": "FINMA does not document what the warning-list Date means. It is stored and reported verbatim with an UNKNOWN dimension and is never renamed to a warning, publication, effective or investigation date, and never used for ordering or state derivation.", "not_covered": [ "IDENTITY_CONFIRMATION", "ILLEGALITY_OR_FRAUD_DETERMINATION", "WARNING_REMOVAL_HISTORY", "WARNING_DATE_SEMANTICS", "NATURAL_PERSON_SCREENING", "UNKNOWN_SUBJECT_TYPE_ENTRY_SCREENING", "SUBJECT_TYPE_DETERMINATION", "WEBSITE_OR_BRAND_SUBJECTS", "COMPLETE_WARNING_LIST_COVERAGE" ], "semantic_boundary": "POSSIBLE_LIST_MATCH means only that a deterministic name comparison produced a candidate among the warning-list entries BUMIT holds that the source explicitly marks as companies. It is never a confirmed identity, and a warning-list entry never means illegal activity, fraud, an unlicensed business or sanctions. NO_DIRECT_LIST_MATCH means only that no direct match was produced among the FINMA warning entries eligible for company screening under the current BUMIT rules; it does not mean the name does not occur anywhere in the complete FINMA warning list, and it never means the absence of regulatory concern. Entries whose subject type the source does not establish are counted but never screened, and their subject type is never inferred from a name, legal-form suffix, commercial-register text or jurisdiction." }, "absence_semantics": "Disappearance from a later dataset never implies withdrawal, revocation or removal. Absence from a list never proves the absence of authorisation or of regulatory concern." }, "x-verification-coverage": { "complete": false, "covered": [ "UID_STRUCTURE", "ENTITY_EXISTENCE", "LEGAL_NAME", "LEGAL_FORM", "REGISTER_STATUS", "ZEFIX_PROVENANCE", "ZEFIX_FRESHNESS" ], "not_covered": [ "SANCTIONS_SCREENING", "VAT_REGISTRATION", "FINMA_AUTHORISATION", "ADDRESS_VALIDATION", "SIGNATORY_AUTHORITY", "INSOLVENCY_STATUS", "REGISTRY_EVENT_HISTORY", "COMPLETE_KYB" ] }, "x-verification-profiles": { "ruleset_version": "1.0.0-phase9", "default_profile": "SWISS_BUSINESS_BASELINE_V1", "profiles": [ { "profile_id": "SWISS_BUSINESS_BASELINE_V1", "profile_version": "1.0.0", "description": "Baseline Swiss business verification: commercial-register existence and register status plus direct SECO sanctions screening. Optional VAT, LEI and official-address evidence is reported but never compensates for unresolved mandatory evidence.", "mandatory_checks": [ "EXISTENCE", "ACTIVE_STATUS", "SANCTIONS" ], "optional_checks": [ "VAT_REGISTRATION", "LEI_LOOKUP", "ADDRESS_VALIDITY" ], "informational_checks": [ "UID_STRUCTURE", "UID_NAME_MATCH", "REGISTRY_EVENTS", "VERIFICATION_COVERAGE" ], "not_required": [ "FINMA_AUTHORISATION_CHECK", "FINMA_WARNING_CHECK", "REGISTERED_SIGNATORY_VERIFY", "IBAN_PAYEE_VERIFY", "TRANSACTION_VERIFY", "COUNTERPARTY_VERIFY" ] } ], "aggregation": "Deterministic and requirement-aware. Mandatory checks alone decide: any mandatory FAIL yields FAIL, otherwise any mandatory REVIEW yields REVIEW, otherwise any mandatory UNKNOWN yields UNKNOWN, otherwise PASS. Zero checks yields UNKNOWN.", "invariants": [ "Optional and informational findings never convert a mandatory outcome, compensate for missing mandatory evidence or turn unresolved mandatory evidence into PASS.", "Stale mandatory evidence never satisfies a mandatory check; the conservative default is UNKNOWN.", "A source outage never produces PASS.", "Synthetic fixture evidence never satisfies a mandatory check in the PRODUCTION evaluation context.", "NOT_APPLICABLE is expressed by applicability, never by overloading UNKNOWN.", "No weighted risk score, majority vote, positive-signal count, probabilistic or fuzzy decisioning and no LLM is involved.", "FINMA authorisation and warning checks are not a requirement for Swiss companies in any profile." ], "pass_semantics": { "meaning": "Every applicable mandatory check of the configured verification profile obtained sufficient usable evidence and none produced REVIEW or FAIL.", "legal_effect": false, "complete_kyb": false, "safe_to_transact": false, "trustworthy": false, "risk_free": false, "solvent": false, "legitimate_for_all_purposes": false, "legal_approval": false, "no_sanctioned_owner_or_controller": false, "no_beneficial_owner_risk": false, "signatory_authority_confirmed": false, "global_sanctions_clearance": false, "weighted_score_used": false, "probabilistic_decision_used": false, "fuzzy_decisioning_used": false, "llm_used": false } }, "x-capabilities": [ { "capability": "COMPANY_SEARCH", "availability": "AVAILABLE", "intent": "Find Swiss commercial-register candidates by company name. Returns candidates, not a verification result.", "sources": [ "ZEFIX" ], "path": "/api/v1/company/search", "partial_coverage": true }, { "capability": "COMPANY_LOOKUP", "availability": "AVAILABLE", "intent": "Retrieve the normalized commercial-register record for a Swiss UID, with provenance and freshness.", "sources": [ "ZEFIX" ], "path": "/api/v1/company/{uid}", "partial_coverage": true }, { "capability": "COMPANY_VERIFY", "availability": "AVAILABLE", "intent": "Establish register-backed existence, registered name, legal form and register status for a Swiss UID. Coverage is partial and never a complete KYB result.", "sources": [ "ZEFIX" ], "path": "/api/v1/company/{uid}/verify", "partial_coverage": true }, { "capability": "COMPANY_EVENTS", "availability": "AVAILABLE", "intent": "Retrieve historical commercial-register publications (SHAB/SOGC) for a Swiss UID, in chronological order. Publications are historical evidence: they never state current company state and never establish signature authority. Live and scheduled SHAB ingestion is currently disabled, so coverage is limited to publications already ingested.", "sources": [ "SHAB" ], "path": "/api/v1/company/{uid}/events", "partial_coverage": true }, { "capability": "REGISTERED_SIGNATORY_LOOKUP", "availability": "NOT_AVAILABLE", "intent": "List registered persons and signature authority. Not implemented; the current source does not publish it.", "sources": [], "path": null, "partial_coverage": false }, { "capability": "REGISTERED_SIGNATORY_VERIFY", "availability": "NOT_AVAILABLE", "intent": "Verify that a named person may sign for a company. Not implemented.", "sources": [], "path": null, "partial_coverage": false }, { "capability": "SANCTIONS_CHECK", "availability": "AVAILABLE", "intent": "Screen a Swiss company directly against the official SECO consolidated sanctions dataset by name. Direct subjects only: a CLEAR result means no direct candidate match was found in the dataset BUMIT checked. It never means the company is not sanctioned, that no sanctioned party owns or controls it, or that it is safe to transact with. Ownership, control, beneficial ownership, natural persons, transactions and non-SECO regimes are out of scope.", "sources": [ "SECO_SANCTIONS" ], "path": "/api/v1/company/{uid}/sanctions", "partial_coverage": true }, { "capability": "FINMA_CHECK", "availability": "NOT_AVAILABLE", "intent": "Single combined FINMA status. Deliberately never implemented: authorisation-list membership and warning-list candidates are different questions with different evidence, and are exposed as FINMA_AUTHORISATION_CHECK and FINMA_WARNING_CHECK instead.", "sources": [], "path": null, "partial_coverage": false }, { "capability": "FINMA_AUTHORISATION_CHECK", "availability": "NOT_AVAILABLE", "intent": "Report whether a canonical Swiss UID appears in the FINMA authorisation-list snapshot BUMIT holds, with FINMA's published authorisation categories preserved verbatim. This is source membership only: FOUND_IN_FINMA_LIST never means authorised, licensed, supervised, compliant or safe, and NOT_FOUND_IN_FINMA_LIST never means not authorised. Linkage is exact canonical UID equality only; no name, city or fuzzy matching is used. FINMA does not guarantee its lists are exhaustive or current, live ingestion is disabled and this deployment runs on synthetic fixtures.", "sources": [ "FINMA" ], "path": "/api/v1/company/{uid}/finma", "partial_coverage": true }, { "capability": "FINMA_WARNING_CHECK", "availability": "NOT_AVAILABLE", "intent": "Report deterministic exact-normalized-name candidates against the FINMA warning-list entries BUMIT holds. A POSSIBLE_LIST_MATCH is a name candidate only: it never confirms identity and never means illegal activity, fraud, an unlicensed business or sanctions. NO_DIRECT_LIST_MATCH means only that no candidate was produced in the entries checked, never the absence of regulatory concern. FINMA states the warning list is neither exhaustive nor updated daily; natural-person entries are excluded, live ingestion is disabled and this deployment runs on synthetic fixtures.", "sources": [ "FINMA" ], "path": "/api/v1/company/{uid}/finma", "partial_coverage": true }, { "capability": "VAT_VERIFY", "availability": "NOT_AVAILABLE", "intent": "Report what the Swiss UID register record BUMIT holds says about a canonical Swiss UID's VAT registration: the source VAT identifier, the source VAT status verbatim, the source VAT entry and end dates, and a normalized result of VAT_ACTIVE, VAT_INACTIVE, NO_VAT_REGISTRATION or UNKNOWN produced by an explicitly versioned status mapping. Linkage is exact canonical UID equality only. A company UID and a VAT UID are different identifiers and are never assumed equal. A valid or assigned UID never means the company is active, VAT_ACTIVE never means safe to transact with or sanctions cleared, VAT_INACTIVE never means the company is inactive or non-existent, and NO_VAT_REGISTRATION — emitted only where the source explicitly establishes absence — never means the company was not found. Unknown or future source statuses yield UNKNOWN, live retrieval is not implemented and this deployment runs on synthetic fixtures.", "sources": [ "UID_VAT" ], "path": "/api/v1/company/{uid}/vat", "partial_coverage": true }, { "capability": "LEI_LOOKUP", "availability": "NOT_AVAILABLE", "intent": "Report whether a stored GLEIF Level 1 record carries the queried canonical Swiss UID as its commercial-register identifier under registration authority RA000548. Linkage is exact identifier equality only: no name, address, city, legal-form or fuzzy matching is used. FOUND never means the company is active, authorised, compliant or safe to transact with; NOT_FOUND never means the company does not exist and is emitted only after a successful lookup against usable stored data; MULTIPLE_RECORDS retains every exact record and resolves none. GLEIF's entity status and LEI registration status are kept separate and verbatim, a GLEIF accounting-consolidating parent is never a beneficial owner or UBO, live retrieval is not implemented and this deployment runs on synthetic fixtures.", "sources": [ "GLEIF" ], "path": "/api/v1/company/{uid}/lei", "partial_coverage": true }, { "capability": "ADDRESS_VERIFY", "availability": "NOT_AVAILABLE", "intent": "Report whether the queried address components correspond exactly to an entry in the official Swiss directory of building addresses (swisstopo) snapshot BUMIT holds, preserving the source status (planned / real / outdated), the separate ADR_OFFICIAL boolean and the federal identifiers ADR_EGAID, BDG_EGID, ADR_EDID, STR_ESID and COM_FOSNR independently and verbatim. Matching is deterministic exact equality on normalized street, house number, postcode and locality; normalization is formatting only and no fuzzy, edit-distance, scored, embedding, LLM, guessed or nearest-geographic matching exists. Results are OFFICIAL_ADDRESS / PLANNED_ADDRESS / OUTDATED_ADDRESS / NOT_FOUND / MULTIPLE_MATCHES / UNKNOWN from an explicitly versioned mapping; an unknown or future source status yields UNKNOWN. OFFICIAL_ADDRESS establishes correspondence with the official directory only: it never means a company is registered, domiciled or operating at the address, that mail is deliverable there, that any company is active, or that a transaction is safe, and no company register address is compared. NOT_FOUND is emitted only after a deterministic lookup against a usable, sufficiently current dataset and never means the address does not exist; MULTIPLE_MATCHES retains every match and resolves none. Live retrieval is not implemented and this deployment runs on synthetic fixtures.", "sources": [ "SWISSTOPO" ], "path": "/api/v1/address/verify", "partial_coverage": true }, { "capability": "COUNTERPARTY_VERIFY", "availability": "NOT_AVAILABLE", "intent": "Composite counterparty verification. Not implemented.", "sources": [], "path": null, "partial_coverage": false }, { "capability": "TRANSACTION_VERIFY", "availability": "NOT_AVAILABLE", "intent": "Pre-payment transaction verification. Not implemented.", "sources": [], "path": null, "partial_coverage": false }, { "capability": "IBAN_PAYEE_VERIFY", "availability": "NOT_AVAILABLE", "intent": "IBAN-to-payee matching. Not implemented.", "sources": [], "path": null, "partial_coverage": false } ], "x-evidence-classification": { "claim_types": [ "SOURCE_FACT", "NORMALIZED", "DERIVED", "INFERRED", "UNAVAILABLE" ], "invariant": "inference_used is true if and only if claim_type is INFERRED. An INFERRED value is never represented as a SOURCE_FACT. Confidence is only present on INFERRED claims.", "inferred_claims_produced": false }, "x-reason-codes": { "all": [ "INVALID_UID", "COMPANY_NOT_FOUND", "SOURCE_NOT_CONFIGURED", "SOURCE_UNAVAILABLE", "SOURCE_TIMEOUT", "SOURCE_RATE_LIMITED", "STALE_EVIDENCE", "INSUFFICIENT_EVIDENCE", "CAPABILITY_NOT_SUPPORTED", "CAPABILITY_NOT_AVAILABLE", "AUTHENTICATION_REQUIRED", "ACCESS_DENIED", "RATE_LIMITED", "UPSTREAM_DEGRADED", "INTERNAL_ERROR", "BAD_REQUEST", "PARTIAL_COVERAGE", "SANCTIONS_NO_DIRECT_MATCH", "SANCTIONS_POSSIBLE_MATCH", "SANCTIONS_CONFIRMED_MATCH", "SANCTIONS_DATA_UNAVAILABLE", "SANCTIONS_DATA_STALE", "SANCTIONS_SCHEMA_UNSUPPORTED", "SANCTIONS_CHECK_INCOMPLETE", "FINMA_LIST_UID_MATCH", "FINMA_LIST_UID_NOT_FOUND", "FINMA_LIST_UID_UNUSABLE", "FINMA_AUTHORISATION_DATA_UNAVAILABLE", "FINMA_AUTHORISATION_DATA_STALE", "FINMA_AUTHORISATION_DATA_INVALID", "FINMA_AUTHORISATION_CHECK_INCOMPLETE", "FINMA_WARNING_NO_DIRECT_MATCH", "FINMA_WARNING_POSSIBLE_MATCH", "FINMA_WARNING_DATA_UNAVAILABLE", "FINMA_WARNING_DATA_STALE", "FINMA_WARNING_DATA_INVALID", "FINMA_WARNING_CHECK_INCOMPLETE", "LEI_RECORD_FOUND", "LEI_RECORD_NOT_FOUND", "LEI_MULTIPLE_RECORDS", "LEI_LINKAGE_IDENTIFIER_UNUSABLE", "LEI_DATA_UNAVAILABLE", "LEI_DATA_INVALID", "LEI_DATA_STALE", "LEI_LOOKUP_INCOMPLETE", "VAT_ACTIVE_REGISTRATION", "VAT_INACTIVE_REGISTRATION", "VAT_NO_REGISTRATION", "VAT_STATUS_UNRECOGNISED", "VAT_EVIDENCE_CONTRADICTORY", "VAT_RECORD_NOT_FOUND", "VAT_MULTIPLE_SOURCE_RECORDS", "VAT_SUBJECT_UID_UNUSABLE", "VAT_DATA_UNAVAILABLE", "VAT_DATA_INVALID", "VAT_DATA_STALE", "VAT_CHECK_INCOMPLETE", "ADDRESS_OFFICIAL_MATCH", "ADDRESS_PLANNED_MATCH", "ADDRESS_OUTDATED_MATCH", "ADDRESS_NOT_FOUND", "ADDRESS_MULTIPLE_MATCHES", "ADDRESS_QUERY_UNUSABLE", "ADDRESS_STATUS_MISSING", "ADDRESS_STATUS_UNRECOGNISED", "ADDRESS_OFFICIAL_FLAG_NOT_SET", "ADDRESS_EVIDENCE_CONTRADICTORY", "ADDRESS_DATA_UNAVAILABLE", "ADDRESS_DATA_INVALID", "ADDRESS_DATA_STALE", "ADDRESS_CHECK_INCOMPLETE", "MANDATORY_CHECK_FAILED", "MANDATORY_CHECK_REVIEW", "MANDATORY_CHECK_UNKNOWN", "VERIFICATION_PROFILE_SATISFIED" ], "active": [ "INVALID_UID", "COMPANY_NOT_FOUND", "SOURCE_NOT_CONFIGURED", "SOURCE_UNAVAILABLE", "SOURCE_TIMEOUT", "SOURCE_RATE_LIMITED", "STALE_EVIDENCE", "INSUFFICIENT_EVIDENCE", "CAPABILITY_NOT_AVAILABLE", "AUTHENTICATION_REQUIRED", "ACCESS_DENIED", "UPSTREAM_DEGRADED", "INTERNAL_ERROR", "BAD_REQUEST", "PARTIAL_COVERAGE", "SANCTIONS_NO_DIRECT_MATCH", "SANCTIONS_POSSIBLE_MATCH", "SANCTIONS_DATA_UNAVAILABLE", "SANCTIONS_DATA_STALE", "SANCTIONS_SCHEMA_UNSUPPORTED", "SANCTIONS_CHECK_INCOMPLETE", "FINMA_LIST_UID_MATCH", "FINMA_LIST_UID_NOT_FOUND", "FINMA_LIST_UID_UNUSABLE", "FINMA_AUTHORISATION_DATA_UNAVAILABLE", "FINMA_AUTHORISATION_DATA_STALE", "FINMA_AUTHORISATION_DATA_INVALID", "FINMA_AUTHORISATION_CHECK_INCOMPLETE", "FINMA_WARNING_NO_DIRECT_MATCH", "FINMA_WARNING_POSSIBLE_MATCH", "FINMA_WARNING_DATA_UNAVAILABLE", "FINMA_WARNING_DATA_STALE", "FINMA_WARNING_DATA_INVALID", "FINMA_WARNING_CHECK_INCOMPLETE", "LEI_RECORD_FOUND", "LEI_RECORD_NOT_FOUND", "LEI_MULTIPLE_RECORDS", "LEI_LINKAGE_IDENTIFIER_UNUSABLE", "LEI_DATA_UNAVAILABLE", "LEI_DATA_INVALID", "LEI_DATA_STALE", "LEI_LOOKUP_INCOMPLETE", "VAT_ACTIVE_REGISTRATION", "VAT_INACTIVE_REGISTRATION", "VAT_NO_REGISTRATION", "VAT_STATUS_UNRECOGNISED", "VAT_EVIDENCE_CONTRADICTORY", "VAT_RECORD_NOT_FOUND", "VAT_MULTIPLE_SOURCE_RECORDS", "VAT_SUBJECT_UID_UNUSABLE", "VAT_DATA_UNAVAILABLE", "VAT_DATA_INVALID", "VAT_DATA_STALE", "VAT_CHECK_INCOMPLETE", "ADDRESS_OFFICIAL_MATCH", "ADDRESS_PLANNED_MATCH", "ADDRESS_OUTDATED_MATCH", "ADDRESS_NOT_FOUND", "ADDRESS_MULTIPLE_MATCHES", "ADDRESS_QUERY_UNUSABLE", "ADDRESS_STATUS_MISSING", "ADDRESS_STATUS_UNRECOGNISED", "ADDRESS_OFFICIAL_FLAG_NOT_SET", "ADDRESS_EVIDENCE_CONTRADICTORY", "ADDRESS_DATA_UNAVAILABLE", "ADDRESS_DATA_INVALID", "ADDRESS_DATA_STALE", "ADDRESS_CHECK_INCOMPLETE", "MANDATORY_CHECK_FAILED", "MANDATORY_CHECK_REVIEW", "MANDATORY_CHECK_UNKNOWN", "VERIFICATION_PROFILE_SATISFIED" ] }, "x-idempotency": { "header": "Idempotency-Key", "operations": [ "verifyCompany" ], "retention_minutes": 10, "replay_header": "Idempotent-Replay", "note": "Retry safety only. No payment or charging behaviour exists." }, "x-planned-paths": [ "/api/v1/company/{uid}/signatories", "/api/v1/company/{uid}/signatory/verify", "/api/v1/company/{uid}/address", "/api/v1/transaction/verify" ] }