{"openapi":"3.1.0","info":{"title":"VeroFlag Public API","version":"2026-06-09","summary":"Server-to-server API for creating VeroFlag cases, polling checks, reviewing matches, and recording permitted decisions.","description":"The public API is designed for trusted backend integrations and agent runtimes. API keys must not be exposed in browser or mobile clients."},"servers":[{"url":"https://veroflag.com/api","description":"Production API namespace"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Groups"},{"name":"Cases"},{"name":"Materials"},{"name":"Checks"},{"name":"Matches"},{"name":"Events"},{"name":"Monitoring"}],"paths":{"/v1/groups":{"get":{"tags":["Groups"],"summary":"List groups visible to the API key.","operationId":"listGroups","responses":{"200":{"description":"Visible groups.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupsEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/cases":{"post":{"tags":["Cases"],"summary":"Create a case and queue selected checks.","description":"Creates or reuses a subject, creates the case immediately, creates queued check records, and runs the selected checks asynchronously.","operationId":"createCase","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCaseRequest"},"examples":{"individualPepSanctions":{"summary":"Individual PEP and sanctions case","value":{"subject":{"mode":"create_or_reuse","type":"person","name":"Vladimir Putin","countries":["RU"],"birth_date":{"year":1952,"month":10,"day":7}},"case":{"group_id":"00000000-0000-0000-0000-000000000000","external_reference":"CRM-12345","notes":"Customer onboarding review."},"checks":{"types":["pep","sanctions"]}}}}}}},"responses":{"201":{"description":"Case created and checks queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/cases/{case_reference}":{"get":{"tags":["Cases"],"summary":"Retrieve a case.","operationId":"getCase","parameters":[{"$ref":"#/components/parameters/CaseReference"}],"responses":{"200":{"description":"Case found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/cases/{case_reference}/decision":{"patch":{"tags":["Cases"],"summary":"Record the final case decision.","description":"Requires case_decisions:write. Agent actors cannot record final case decisions in the MVP.","operationId":"updateCaseDecision","parameters":[{"$ref":"#/components/parameters/CaseReference"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionRequest"}}}},"responses":{"200":{"description":"Case decision updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/cases/{case_reference}/materials":{"post":{"tags":["Materials"],"summary":"Add a case material note or link.","description":"Requires materials:write. Adds a case-wide material entry for notes, links, or both. Binary file upload is intentionally deferred to a future signed-upload endpoint.","operationId":"createCaseMaterial","parameters":[{"$ref":"#/components/parameters/CaseReference"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCaseMaterialRequest"},"examples":{"noteAndLink":{"summary":"Add a note with supporting link","value":{"title":"EDD note","note":"Customer support team requested enhanced review.","url":"https://example.com/internal-ticket/12345"}}}}}},"responses":{"201":{"description":"Case material added.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseMaterialEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/cases/{case_reference}/events":{"get":{"tags":["Events"],"summary":"List API-visible case activity events.","description":"Requires events:read. Returns allowlisted case workflow events for a case visible to the API key. Internal audit-only events are intentionally excluded.","operationId":"listCaseEvents","parameters":[{"$ref":"#/components/parameters/CaseReference"},{"name":"event_type","in":"query","required":false,"schema":{"$ref":"#/components/schemas/CaseEventType"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Case events returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CaseEventsEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/checks/{check_reference}":{"get":{"tags":["Checks"],"summary":"Retrieve a check.","operationId":"getCheck","parameters":[{"$ref":"#/components/parameters/CheckReference"}],"responses":{"200":{"description":"Check found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/checks/{check_reference}/decision":{"patch":{"tags":["Checks"],"summary":"Record a check decision.","description":"Requires checks:decide. Potential matches on the check must be reviewed before a pass, conditional pass, or fail decision can be recorded.","operationId":"updateCheckDecision","parameters":[{"$ref":"#/components/parameters/CheckReference"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionRequest"}}}},"responses":{"200":{"description":"Check decision updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/matches/{match_id}/review":{"patch":{"tags":["Matches"],"summary":"Review a potential match.","operationId":"reviewMatch","parameters":[{"$ref":"#/components/parameters/MatchId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewMatchRequest"}}}},"responses":{"200":{"description":"Match review updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/monitoring-configs":{"get":{"tags":["Monitoring"],"summary":"List monitoring configurations visible to the API key.","description":"Requires monitoring:read. Returns subject monitoring configurations within the API key workspace and group scope.","operationId":"listMonitoringConfigs","parameters":[{"name":"subject_reference","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","paused"]}},{"name":"latest_result","in":"query","required":false,"schema":{"$ref":"#/components/schemas/MonitoringResult"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Monitoring configurations returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitoringConfigListEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"tags":["Monitoring"],"summary":"Enroll a subject for ongoing monitoring.","description":"Requires monitoring:write and an Idempotency-Key header. If the subject is already monitored in the selected group, this endpoint updates the existing configuration.","operationId":"createMonitoringConfig","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMonitoringConfigRequest"}}}},"responses":{"200":{"description":"Existing monitoring config updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitoringConfigEnvelope"}}}},"201":{"description":"Monitoring config created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitoringConfigEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/monitoring-configs/{monitoring_config_id}":{"get":{"tags":["Monitoring"],"summary":"Retrieve a monitoring configuration and latest result.","operationId":"getMonitoringConfig","parameters":[{"$ref":"#/components/parameters/MonitoringConfigId"}],"responses":{"200":{"description":"Monitoring config found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitoringConfigEnvelope"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"tags":["Monitoring"],"summary":"Update a monitoring configuration.","description":"Requires monitoring:write and an Idempotency-Key header. Owner and collaborators must be members of the selected group.","operationId":"updateMonitoringConfig","parameters":[{"$ref":"#/components/parameters/MonitoringConfigId"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMonitoringConfigRequest"}}}},"responses":{"200":{"description":"Monitoring config updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitoringConfigEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/monitoring-configs/{monitoring_config_id}/runs":{"get":{"tags":["Monitoring"],"summary":"List recent monitoring runs for one configuration.","operationId":"listMonitoringRuns","parameters":[{"$ref":"#/components/parameters/MonitoringConfigId"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Monitoring runs returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitoringRunsEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/monitoring-configs/{monitoring_config_id}/alerts":{"get":{"tags":["Monitoring"],"summary":"List monitoring alerts for changed known matches.","description":"Requires monitoring:read. Alerts represent material changes to previously observed matches and include recommended next actions.","operationId":"listMonitoringAlerts","parameters":[{"$ref":"#/components/parameters/MonitoringConfigId"},{"name":"resolution_status","in":"query","required":false,"schema":{"type":"string","enum":["pending","creating_follow_up_case","no_action_required","follow_up_case_created"]}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Monitoring alerts returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitoringAlertsEnvelope"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"webhooks":{"publicApiEvent":{"post":{"tags":["Webhooks"],"summary":"Receive a VeroFlag public API webhook event.","description":"Webhook endpoints receive signed POST requests for the event types selected in Settings > API. Delivery is at least once; handlers must be idempotent by event id.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload"},"examples":{"checkCompletedExpanded":{"summary":"Expanded check.completed payload","value":{"id":"evt_01HX83AF7X4N28P8VM7RSGFHFG","type":"check.completed","api_version":"2026-06-09","created_at":"2026-06-09T12:00:06Z","data":{"account_id":"00000000-0000-0000-0000-000000000000","group_id":"00000000-0000-0000-0000-000000000000","object":{"id":"MMS450000-1","type":"check"},"case_reference":"MMS450000","check_reference":"MMS450000-1","lifecycle_status":"completed","match_count":1,"screening_record_id":"scr_2609_120006_1","screening_type":"sanctions","subject_name":"Vladimir Putin"}}}}}}},"responses":{"200":{"description":"Webhook accepted."},"204":{"description":"Webhook accepted with no response body."}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Use a VeroFlag API key created in Settings > API."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":160},"description":"Required for mutation endpoints."},"CaseReference":{"name":"case_reference","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}[0-9]{6}$"}},"CheckReference":{"name":"check_reference","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}[0-9]{6}-[0-9]+$"}},"MatchId":{"name":"match_id","in":"path","required":true,"schema":{"type":"string"}},"MonitoringConfigId":{"name":"monitoring_config_id","in":"path","required":true,"schema":{"type":"string","pattern":"^mon_[a-f0-9]+$"}}},"responses":{"BadRequest":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Forbidden":{"description":"API key is not permitted to perform this action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Requested object was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"Conflict":{"description":"Idempotency conflict or conflicting object state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"UnprocessableEntity":{"description":"Request is valid JSON but cannot be applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Rate limit exceeded. Public API routes are limited to 120 requests per 60 seconds and return error code rate_limited with a request id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"schemas":{"GroupsEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["groups"],"properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/Group"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"Group":{"type":"object","required":["id","account_id","name","slug","is_default"],"properties":{"id":{"type":"string","format":"uuid"},"account_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":["string","null"]},"is_default":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CreateCaseRequest":{"type":"object","required":["subject","checks"],"properties":{"subject":{"$ref":"#/components/schemas/CreateCaseSubject"},"case":{"$ref":"#/components/schemas/CreateCaseWorkflow"},"checks":{"$ref":"#/components/schemas/CreateCaseChecks"},"monitoring":{"$ref":"#/components/schemas/CreateCaseMonitoring"}}},"CreateCaseSubject":{"type":"object","properties":{"mode":{"type":"string","enum":["create_or_reuse","existing"],"default":"create_or_reuse"},"subject_reference":{"type":["string","null"]},"type":{"type":"string","enum":["person","company","organization","vessel","aircraft","vehicle","unknown"],"default":"person"},"name":{"type":["string","null"],"maxLength":240},"countries":{"type":"array","items":{"type":"string","minLength":2,"maxLength":2},"maxItems":20,"default":[]},"birth_date":{"$ref":"#/components/schemas/BirthDate"},"external_reference":{"type":["string","null"],"maxLength":200},"metadata":{"type":"object","additionalProperties":true}}},"BirthDate":{"type":["object","null"],"properties":{"year":{"type":"integer","minimum":1800,"maximum":2100},"month":{"type":"integer","minimum":1,"maximum":12},"day":{"type":"integer","minimum":1,"maximum":31}}},"CreateCaseWorkflow":{"type":"object","properties":{"group_id":{"type":["string","null"],"format":"uuid"},"owner_user_id":{"type":["string","null"],"format":"uuid"},"collaborator_user_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50,"default":[]},"external_reference":{"type":["string","null"],"maxLength":200},"notes":{"type":["string","null"],"maxLength":4000},"metadata":{"type":"object","additionalProperties":true}}},"CreateCaseChecks":{"type":"object","required":["types"],"properties":{"types":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","enum":["pep","sanctions","business_entity_risk"]}},"screening_profile_id":{"type":["string","null"],"maxLength":120}}},"CreateCaseMonitoring":{"type":"object","properties":{"enable":{"type":"boolean","default":false},"owner_user_id":{"type":["string","null"],"format":"uuid"},"collaborator_user_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50,"default":[]}}},"CaseEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Case"},"meta":{"$ref":"#/components/schemas/Meta"}}},"CheckEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Check"},"meta":{"$ref":"#/components/schemas/Meta"}}},"MatchEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Match"},"meta":{"$ref":"#/components/schemas/Meta"}}},"CaseMaterialEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/CaseMaterial"},"meta":{"$ref":"#/components/schemas/Meta"}}},"CaseEventsEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["case_reference","events","next_cursor"],"properties":{"case_reference":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"events":{"type":"array","items":{"$ref":"#/components/schemas/CaseEvent"}},"next_cursor":{"type":["string","null"]}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"MonitoringConfigListEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["monitoring_configs"],"properties":{"monitoring_configs":{"type":"array","items":{"$ref":"#/components/schemas/MonitoringConfig"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"MonitoringConfigEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/MonitoringConfig"},"meta":{"$ref":"#/components/schemas/Meta"}}},"MonitoringRunsEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["monitoring_config_id","subject_reference","group_id","runs"],"properties":{"monitoring_config_id":{"type":"string"},"subject_reference":{"type":["string","null"]},"group_id":{"type":"string","format":"uuid"},"runs":{"type":"array","items":{"$ref":"#/components/schemas/MonitoringRun"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"MonitoringAlertsEnvelope":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","required":["monitoring_config_id","subject_reference","group_id","alerts"],"properties":{"monitoring_config_id":{"type":"string"},"subject_reference":{"type":["string","null"]},"group_id":{"type":"string","format":"uuid"},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/MonitoringAlert"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}},"CreateMonitoringConfigRequest":{"type":"object","required":["subject_reference","check_types"],"properties":{"subject_reference":{"type":"string","example":"SRI502707"},"check_types":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","enum":["pep","sanctions","business_entity_risk"]}},"group_id":{"type":["string","null"],"format":"uuid"},"owner_user_id":{"type":["string","null"],"format":"uuid"},"collaborator_user_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50,"default":[]},"status":{"type":"string","enum":["active","paused"]},"metadata":{"type":"object","additionalProperties":true}}},"UpdateMonitoringConfigRequest":{"type":"object","properties":{"check_types":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"type":"string","enum":["pep","sanctions","business_entity_risk"]}},"group_id":{"type":["string","null"],"format":"uuid"},"owner_user_id":{"type":["string","null"],"format":"uuid"},"collaborator_user_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":50},"status":{"type":"string","enum":["active","paused"]},"metadata":{"type":"object","additionalProperties":true}}},"MonitoringConfig":{"type":"object","required":["monitoring_config_id","group_id","owner_user_id","status","check_types","latest_result","created_at","updated_at"],"properties":{"monitoring_config_id":{"type":"string"},"subject_reference":{"type":["string","null"]},"subject":{"$ref":"#/components/schemas/MonitoringSubject"},"group_id":{"type":"string","format":"uuid"},"group":{"$ref":"#/components/schemas/MonitoringGroup"},"owner_user_id":{"type":"string","format":"uuid"},"collaborator_user_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"status":{"type":"string","enum":["active","paused"]},"check_types":{"type":"array","items":{"type":"string","enum":["pep","sanctions","business_entity_risk"]}},"last_checked_at":{"type":["string","null"],"format":"date-time"},"last_change_detected_at":{"type":["string","null"],"format":"date-time"},"latest_result":{"$ref":"#/components/schemas/MonitoringResult"},"latest_result_label":{"type":"string"},"latest_result_summary":{"type":["string","null"]},"latest_run_id":{"type":["string","null"]},"open_follow_up_case_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"allowed_actions":{"type":"array","items":{"type":"string"}},"recommended_next_actions":{"type":"array","items":{"type":"string"}}}},"MonitoringSubject":{"type":["object","null"],"properties":{"subject_reference":{"type":"string"},"type":{"type":"string"},"display_name":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}},"birth_date":{"$ref":"#/components/schemas/BirthDate"},"external_reference":{"type":["string","null"]}}},"MonitoringGroup":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"}}},"MonitoringResult":{"type":"string","enum":["not_checked","no_change","new_matches","changed_matches","failed","skipped"]},"MonitoringRun":{"type":"object","properties":{"monitoring_run_id":{"type":"string"},"monitoring_config_id":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["running","completed","failed","skipped"]},"check_types":{"type":"array","items":{"type":"string","enum":["pep","sanctions","business_entity_risk"]}},"source_snapshot_ids":{"type":"array","items":{"type":"string"}},"source_snapshot_version":{"type":["string","null"]},"started_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"result":{"type":"string","enum":["running","no_change","new_matches","changed_matches","failed","skipped"]},"result_label":{"type":"string"},"result_summary":{"type":["string","null"]},"match_count":{"type":"integer"},"new_match_count":{"type":"integer"},"changed_match_count":{"type":"integer"},"unchanged_match_count":{"type":"integer"},"created_case_reference":{"type":["string","null"]},"error_message":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"MonitoringAlert":{"type":"object","properties":{"alert_id":{"type":"string"},"monitoring_config_id":{"type":"string"},"monitoring_run_id":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"check_type":{"type":"string","enum":["pep","sanctions","business_entity_risk"]},"screening_type":{"type":"string","enum":["pep","sanctions","business_entity_risk"]},"match_fingerprint":{"type":"string"},"matched_entity_id":{"type":["string","null"]},"source":{"$ref":"#/components/schemas/MonitoringSource"},"display_name":{"type":"string"},"score":{"type":["integer","null"]},"confidence_band":{"type":["string","null"]},"change_summary":{"type":"string"},"changes":{"type":"array","items":{"type":"object"}},"previous_snapshot":{"type":"object","additionalProperties":true},"current_snapshot":{"type":"object","additionalProperties":true},"current_match":{"type":"object","additionalProperties":true},"resolution_status":{"type":"string","enum":["pending","creating_follow_up_case","no_action_required","follow_up_case_created"]},"resolution_note":{"type":["string","null"]},"resolved_at":{"type":["string","null"],"format":"date-time"},"created_case_reference":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"allowed_actions":{"type":"array","items":{"type":"string"}},"recommended_next_actions":{"type":"array","items":{"type":"string"}}}},"MonitoringSource":{"type":"object","properties":{"name":{"type":["string","null"]},"record_reference":{"type":["string","null"]}}},"CreateCaseMaterialRequest":{"type":"object","required":["title"],"properties":{"title":{"type":"string","minLength":1,"maxLength":160},"note":{"type":["string","null"],"maxLength":4000},"url":{"type":["string","null"],"format":"uri","maxLength":1000}},"description":"Provide title and at least one of note or url. File uploads are not accepted by this endpoint."},"Case":{"type":"object","required":["case_reference","subject","group_id","decision","checks","created_at","updated_at"],"properties":{"case_reference":{"type":"string"},"subject":{"$ref":"#/components/schemas/Subject"},"group_id":{"type":"string","format":"uuid"},"owner_user_id":{"type":["string","null"],"format":"uuid"},"collaborator_user_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"decision":{"type":"string","enum":["pending_decision","pass","conditional_pass","fail"]},"decision_notes":{"type":["string","null"]},"resolved_by":{"type":["string","null"]},"resolved_at":{"type":["string","null"],"format":"date-time"},"external_reference":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":true},"checks":{"type":"array","items":{"$ref":"#/components/schemas/Check"}},"materials":{"type":"array","items":{"$ref":"#/components/schemas/CaseMaterial"}},"created_by_actor":{"$ref":"#/components/schemas/Actor"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"allowed_actions":{"type":"array","items":{"type":"string"}},"recommended_next_actions":{"type":"array","items":{"type":"string"}},"requires_human_review":{"type":"boolean"}}},"Subject":{"type":"object","required":["subject_reference","type","display_name"],"properties":{"subject_reference":{"type":["string","null"]},"type":{"type":"string"},"display_name":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}},"birth_date":{"$ref":"#/components/schemas/BirthDate"},"external_reference":{"type":["string","null"]},"metadata":{"type":"object","additionalProperties":true}}},"Check":{"type":"object","required":["check_reference","id","type","lifecycle_status","decision","match_count"],"properties":{"check_reference":{"type":"string"},"id":{"type":"string"},"type":{"type":"string","enum":["pep","sanctions","business_entity_risk"]},"lifecycle_status":{"type":"string","enum":["queued","running","completed","failed"]},"decision":{"type":"string","enum":["pending_review","no_matches_found","pass","conditional_pass","fail"]},"match_count":{"type":"integer"},"top_score":{"type":["number","null"]},"case_reference":{"type":"string"},"subject_reference":{"type":["string","null"]},"decision_notes":{"type":["string","null"]},"decided_at":{"type":["string","null"],"format":"date-time"},"decided_by":{"type":["string","null"]},"checked_at":{"type":["string","null"],"format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"failure_reason":{"type":["string","null"]},"result_summary":{"type":"object","additionalProperties":true},"matches":{"type":"array","items":{"$ref":"#/components/schemas/Match"}},"blocking_items":{"type":"array","items":{"type":"string"}},"allowed_actions":{"type":"array","items":{"type":"string"}},"recommended_next_actions":{"type":"array","items":{"type":"string"}}}},"Match":{"type":"object","required":["match_id","rank","display_name","review_status","score"],"properties":{"match_id":{"type":"string"},"rank":{"type":"integer"},"display_name":{"type":"string"},"matched_entity_id":{"type":["string","null"]},"review_status":{"type":"string","enum":["pending_review","confirmed_match","not_relevant"]},"score":{"type":"number"},"match_type":{"type":"string"},"reason":{"type":"object","additionalProperties":true},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"source_record_ref":{"type":["string","null"]},"source_snapshot_id":{"type":["string","null"]},"supporting_fields":{"type":"object","additionalProperties":true},"review":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"Source":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":["string","null"],"format":"uri"},"dataset":{"type":["string","null"]},"priority":{"type":"integer"}}},"CaseMaterial":{"type":"object","required":["material_id","case_reference","type","status","title","attachments","created_at","updated_at"],"properties":{"material_id":{"type":"string"},"case_reference":{"type":"string"},"type":{"type":"string","enum":["note","link","file","mixed"]},"status":{"type":"string","enum":["pending","available","failed"]},"group_id":{"type":"string","format":"uuid"},"title":{"type":["string","null"]},"note":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"},"check_id":{"type":["string","null"]},"created_by_actor":{"$ref":"#/components/schemas/Actor"},"finalized_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/CaseMaterialAttachment"}}}},"CaseMaterialAttachment":{"type":"object","properties":{"attachment_id":{"type":"string"},"filename":{"type":"string"},"content_type":{"type":"string"},"byte_size":{"type":"integer"},"status":{"type":"string","enum":["pending","available","failed"]},"finalized_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"CaseEventType":{"type":"string","enum":["case_created","case_review_started","case_reopened","case_group_changed","case_owner_changed","case_collaborators_added","case_collaborators_removed","case_external_reference_updated","case_reference_added","case_attachment_added","comment_added","check_completed","check_failed","match_disposition_recorded","check_decision_recorded","case_decision_recorded","case_decision_draft_saved","case_decision_reason_saved"]},"CaseEvent":{"type":"object","required":["event_id","event_type","object_type","object_reference","case_reference","group_id","actor","summary","payload","occurred_at","created_at"],"properties":{"event_id":{"type":"string"},"event_type":{"$ref":"#/components/schemas/CaseEventType"},"object_type":{"type":"string","enum":["case"]},"object_reference":{"type":"string"},"case_reference":{"type":"string"},"group_id":{"type":"string","format":"uuid"},"actor":{"$ref":"#/components/schemas/Actor"},"summary":{"type":"string"},"comment":{"type":["string","null"]},"payload":{"type":"object","additionalProperties":true},"occurred_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"Actor":{"type":"object","properties":{"type":{"type":"string","enum":["human","api_client","agent","system"]},"id":{"type":["string","null"]},"display_name":{"type":["string","null"]}}},"WebhookPayload":{"type":"object","required":["id","type","api_version","created_at","data"],"properties":{"id":{"type":"string","pattern":"^evt_[a-f0-9]+$"},"type":{"$ref":"#/components/schemas/WebhookEventType"},"api_version":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"data":{"$ref":"#/components/schemas/WebhookPayloadData"}}},"WebhookEventType":{"type":"string","enum":["case.created","check.completed","check.failed","match.reviewed","check.decision_updated","case.decision_recorded","monitoring.alert_created"]},"WebhookPayloadData":{"type":"object","required":["account_id","group_id","object"],"properties":{"account_id":{"type":"string","format":"uuid"},"group_id":{"type":["string","null"],"format":"uuid"},"object":{"$ref":"#/components/schemas/WebhookObject"}},"additionalProperties":true,"description":"Summary mode includes account_id, group_id, and object. Expanded mode also includes event-specific fields such as case_reference, check_reference, match_id, monitoring_config_id, alert_id, and decision data."},"WebhookObject":{"type":"object","required":["id","type"],"properties":{"id":{"type":["string","null"]},"type":{"type":"string","enum":["case","check","match","monitoring"]}}},"DecisionRequest":{"type":"object","required":["decision"],"properties":{"decision":{"type":"string","enum":["pass","conditional_pass","fail"]},"decision_notes":{"type":["string","null"],"maxLength":4000}}},"ReviewMatchRequest":{"type":"object","required":["review_status"],"properties":{"review_status":{"type":"string","enum":["pending_review","confirmed_match","not_relevant"]},"note":{"type":["string","null"],"maxLength":2000}}},"Meta":{"type":"object","properties":{"request_id":{"type":"string"}}},"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}}