{ "components": { "securitySchemes": { "bearerAuth": { "bearerFormat": "API Key", "description": "API key obtained from the Verifex dashboard (format: `vfx_`). Keys are shown once at creation.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Fraud and AML transaction monitoring: decisions, cases, rules (tune → simulate → deploy), lists, risk tables, customer risk, reports and webhooks. Bearer API key. Enabled per account (fraud_monitoring); an account without it gets 404 on every path. The SanctionScanner-compatible /api/* surface is documented separately.", "title": "Verifex Shield API (native)", "version": "1.0.0" }, "openapi": "3.0.3", "paths": { "/v1/risk/alarm-thresholds": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Alarm thresholds: the totalScore at or above which a decision's triggered alarm is VeryLow … Critical", "tags": [ "Risk" ] }, "put": { "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Set alarm thresholds { veryLow, low, medium, high, critical } (non-decreasing). Takes effect on the next decision.", "tags": [ "Risk" ] } }, "/v1/risk/blacklist": { "get": { "parameters": [ { "in": "query", "name": "key_type", "required": false, "schema": { "enum": [ "device_id", "ip_hash", "card_hash", "actor_user_id", "account_hash", "identity_doc_hash", "customer_hash" ], "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "List active (non-removed) blacklist entries for this tenant", "tags": [ "Risk" ] }, "post": { "description": "Blocks a customer, account/IBAN, identity document, IP or device in every Shield decision for this tenant. Values other than device ids are stored as keyed HMAC digests, never raw. Manual only: Shield never blacklists automatically unless the tenant opts in.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Add a blacklist entry (analyst action, reason required)", "tags": [ "Risk" ] } }, "/v1/risk/blacklist/{id}": { "delete": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Remove a blacklist entry (soft delete, audit-logged)", "tags": [ "Risk" ] } }, "/v1/risk/cases": { "get": { "parameters": [ { "in": "query", "name": "engine", "required": false, "schema": { "enum": [ "v1", "shield" ], "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "assigned_to", "required": false, "schema": { "maxLength": 64, "type": "string" } }, { "in": "query", "name": "outcome", "required": false, "schema": { "enum": [ "clear", "review", "escalate", "delay", "block" ], "type": "string" } }, { "in": "query", "name": "final_verdict", "required": false, "schema": { "enum": [ "confirmed", "false_positive", "inconclusive" ], "type": "string" } }, { "in": "query", "name": "transaction_id", "required": false, "schema": { "maxLength": 200, "type": "string" } }, { "in": "query", "name": "from", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "to", "required": false, "schema": { "format": "date-time", "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 64, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Shield cases for this tenant", "tags": [ "Risk" ] } }, "/v1/risk/cases/{id}": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve a Shield case with its decision", "tags": [ "Risk" ] }, "patch": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update a Shield case: status, verdict, match status, assignee, team, tags, note, reopen", "tags": [ "Risk" ] } }, "/v1/risk/cases/{id}/decision": { "post": { "description": "The ONLY path that writes to the blacklist registry in Sprint 1 — there is no automatic blacklisting. Set `apply_blacklist: true` with a `blacklist_reason` on a decision to manually blacklist every device/IP/card/actor identifier known on the underlying event.", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Record an analyst decision on a Shield case", "tags": [ "Risk" ] } }, "/v1/risk/currency-risk-levels": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "The account's currency risk levels", "tags": [ "Risk" ] }, "put": { "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Set currency risk levels: { items: [{ currencyCode (AZN or 944), riskLevel: Low|Medium|High }] }. An empty level is ignored.", "tags": [ "Risk" ] } }, "/v1/risk/currency-risk-levels/{code}": { "delete": { "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "maxLength": 3, "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Remove a currency's risk level", "tags": [ "Risk" ] } }, "/v1/risk/customer-risk-thresholds": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Customer risk-level thresholds (score at or above: 1 VeryLow … 5 Critical)", "tags": [ "Risk" ] }, "put": { "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Set customer risk-level thresholds", "tags": [ "Risk" ] } }, "/v1/risk/customers/{customer}/baseline": { "get": { "parameters": [ { "in": "path", "name": "customer", "required": true, "schema": { "maxLength": 256, "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "A customer's behavioural baseline (what 'normal' is for TXN_11/12/14)", "tags": [ "Risk" ] } }, "/v1/risk/customers/{customer}/risk": { "get": { "parameters": [ { "in": "path", "name": "customer", "required": true, "schema": { "maxLength": 256, "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "A registered customer's risk score, level and every adjustment behind it", "tags": [ "Risk" ] }, "post": { "parameters": [ { "in": "path", "name": "customer", "required": true, "schema": { "maxLength": 256, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Raise or lower a registered customer's risk score: { delta (non-zero integer), reason }", "tags": [ "Risk" ] } }, "/v1/risk/decisions": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Shield decisions (server-side filters, keyset pagination, counts over the full range)", "tags": [ "Risk" ] } }, "/v1/risk/decisions/{id}": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve a Shield decision (with evidence capsule)", "tags": [ "Risk" ] } }, "/v1/risk/decisions/{id}/replay": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replay a Shield decision from its capsule and the rule versions it recorded", "tags": [ "Risk" ] } }, "/v1/risk/events": { "get": { "parameters": [ { "in": "query", "name": "event_type", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "List Shield events for this tenant, with their latest decision", "tags": [ "Risk" ] }, "post": { "description": "Screens a transaction/session event against the tenant's rule policy (or the generic default catalog in shadow mode, for tenants with no configured rules) and returns a verdict, score breakdown, and evidence capsule. Idempotent on `external_event_id` — a repeated call replays the original decision rather than reprocessing.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Ingest an event and receive a Shield decision", "tags": [ "Risk" ] } }, "/v1/risk/feedback": { "post": { "description": "Feeds ground truth (legit/fraud/chargeback/etc) back for a decision. Used to measure and later tune rule/model quality — not consumed synchronously by the decision engine in V1.", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Report the real-world outcome of a past decision", "tags": [ "Risk" ] } }, "/v1/risk/mcc-codes": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "The account's MCC table (risk level 1 Low, 2 Medium, 3 High)", "tags": [ "Risk" ] }, "put": { "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Add or update MCC codes: { items: [{ mccCode, name, description?, riskLevel: Low|Medium|High, dailySectorAverage? }] }. Invalid rows are skipped and reported.", "tags": [ "Risk" ] } }, "/v1/risk/mcc-codes/{code}": { "delete": { "parameters": [ { "in": "path", "name": "code", "required": true, "schema": { "pattern": "^\\d{1,4}$", "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Remove an MCC code from the table", "tags": [ "Risk" ] } }, "/v1/risk/operators": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Case assignees (the tenant's review team directory)", "tags": [ "Risk" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Add a case assignee", "tags": [ "Risk" ] } }, "/v1/risk/operators/{id}": { "delete": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Deactivate a case assignee", "tags": [ "Risk" ] } }, "/v1/risk/reports/behaviour": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "AML behaviour report S1–S4 for a month (json, csv or xlsx)", "tags": [ "Risk" ] } }, "/v1/risk/reports/monthly": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Monthly Shield summary: decisions by outcome, alarms, cases, verdicts and AML firings", "tags": [ "Risk" ] } }, "/v1/risk/rules": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "List the tenant's Shield rules with their definitions", "tags": [ "Risk" ] } }, "/v1/risk/rules/{id}": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retrieve one Shield rule (by rule GUID)", "tags": [ "Risk" ] }, "patch": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Tune a Shield rule (params, score, mode, condition). Requires rationale and approvedBy; takes effect on the next decision.", "tags": [ "Risk" ] } }, "/v1/risk/rules/{id}/simulate": { "post": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Simulate a proposed rule change over the last N days (default 30) of decisions. Queued; poll GET /v1/risk/simulations/:id. Deploy the same change with PATCH /v1/risk/rules/:id and simulationId.", "tags": [ "Risk" ] } }, "/v1/risk/rules/{id}/simulations": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "A rule's recent simulations (newest first)", "tags": [ "Risk" ] } }, "/v1/risk/rules/{id}/versions": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "A Shield rule's Parameter Register (every version, who changed and approved it, why)", "tags": [ "Risk" ] } }, "/v1/risk/schema/events": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Runtime schema discovery: accepted transaction fields, rule features, operators", "tags": [ "Risk" ] } }, "/v1/risk/settings": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Shield settings: AML time zone and case SLA hours", "tags": [ "Risk" ] }, "put": { "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update Shield settings. A time-zone change affects months of events received from now on; past months keep the zone they were counted in.", "tags": [ "Risk" ] } }, "/v1/risk/simulations/{id}": { "get": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "One simulation: status and, once completed, the comparison", "tags": [ "Risk" ] } }, "/v1/risk/tags": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Case tags", "tags": [ "Risk" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Add a case tag", "tags": [ "Risk" ] } }, "/v1/risk/teams": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Review teams", "tags": [ "Risk" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Add a review team", "tags": [ "Risk" ] } }, "/v1/risk/webhook-events": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "The webhook events Shield emits, with what each means", "tags": [ "Risk" ] } }, "/v1/risk/whitelist": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "List active whitelist entries", "tags": [ "Risk" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Add a whitelist entry (lowers a behaviour-driven outcome one step; never sanctions or a blacklist hit)", "tags": [ "Risk" ] } }, "/v1/risk/whitelist/{id}": { "delete": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Remove a whitelist entry (soft delete, audit-logged)", "tags": [ "Risk" ] } }, "/v1/webhooks": { "get": { "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "List all webhooks", "tags": [ "Webhooks" ] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "events": { "items": { "enum": [ "screening.match_changed", "screening.coverage_degraded", "screening.retroactive_change", "list.sync_completed", "list.sync_failed", "risk.decision.created", "risk.case.opened", "transaction.alert_updated", "transaction.status_updated", "transaction.match_status_updated", "case.assigned", "case.closed", "case.tag_set", "account.blacklisted", "account.whitelisted", "customer.blacklisted", "customer.whitelisted", "behaviour.report_ready", "rule.changed", "scan.match_status_updated", "scan.risk_level_updated", "scan.case_closed" ], "type": "string" }, "type": "array" }, "url": { "format": "uri", "type": "string" } }, "required": [ "url" ], "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Register a new webhook", "tags": [ "Webhooks" ] } }, "/v1/webhooks/deliveries": { "get": { "description": "Returns the last 100 webhook delivery attempts (delivered, failed, or pending) across all the authenticated user's webhooks. `events` (comma-separated) narrows it to those events — filtered in the query, so the 100 are the latest of those events.", "parameters": [ { "in": "query", "name": "events", "required": false, "schema": { "maxLength": 2000, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Default Response" }, "400": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "List recent webhook delivery attempts", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{id}": { "delete": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete a webhook", "tags": [ "Webhooks" ] }, "patch": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "maxLength": 64, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": true, "type": "object" } } }, "required": true }, "responses": { "200": { "description": "Default Response" } }, "security": [ { "bearerAuth": [] } ], "summary": "Change a webhook's events or pause/resume it", "tags": [ "Webhooks" ] } } }, "servers": [ { "description": "Production", "url": "https://api.verifex.dev" } ] }