CompanySanctionsResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/bumit-ai/json-schema/bumit-ai-company-sanctions-response-schema.json",
  "title": "CompanySanctionsResponse",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/_original/bumit-ai-v1-openapi.json#/components/schemas/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": "#/$defs/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": "#/$defs/SanctionsCandidate"
      }
    },
    "freshness": {
      "$ref": "#/$defs/Freshness"
    },
    "claims": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/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": "#/$defs/Meta"
    }
  },
  "$defs": {
    "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": "#/$defs/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": "#/$defs/ReasonCode"
        }
      }
    },
    "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."
    },
    "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": "#/$defs/SourceState"
        },
        "upstream_status": {
          "$ref": "#/$defs/UpstreamStatus"
        },
        "reason_code": {
          "anyOf": [
            {
              "$ref": "#/$defs/ReasonCode"
            },
            {
              "type": "null"
            }
          ]
        }
      }
    },
    "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"
        }
      }
    },
    "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"
      ]
    },
    "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"
        }
      }
    },
    "SanctionsCheckState": {
      "type": "string",
      "enum": [
        "CLEAR",
        "POSSIBLE_MATCH",
        "CONFIRMED_MATCH",
        "UNKNOWN"
      ]
    },
    "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."
    }
  }
}