Case Management

Overview

Cases are the core workflow unit for compliance teams. A case is automatically created whenever a transaction receives a REVIEW, ESCALATE, or BLOCK outcome. Cases can also be created manually by compliance officers for ad-hoc investigations.

Common Workflows

Automatic case creation: A transaction triggers a sanctions hit → The system creates a SANCTIONS_HIT case → Compliance officers are notified via email and dashboard → An officer claims the case, investigates, and resolves it. Manual investigation: An analyst notices a pattern → Creates a REGULATORY_INQUIRY case → Attaches related transactions → Adds investigation notes → Escalates to a senior officer.

Permissions

Action	Who Can Do It
Create case	`BANK_ADMIN`, `COMPLIANCE_OFFICER`, `ANALYST`
List, view cases	All authenticated users
Update status, assign	`BANK_ADMIN`, `COMPLIANCE_OFFICER`
Add notes	All authenticated users

Case Lifecycle

OPEN → IN_PROGRESS → PENDING_REVIEW → ESCALATED → RESOLVED_TRUE_POSITIVE / RESOLVED_FALSE_POSITIVE → CLOSED

Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/cases`	Create a new case
`GET`	`/api/v1/cases`	List cases with filters
`GET`	`/api/v1/cases/:id`	Retrieve case details
`PATCH`	`/api/v1/cases/:id/status`	Update case status
`PATCH`	`/api/v1/cases/:id/assign`	Assign case to a user
`POST`	`/api/v1/cases/:id/notes`	Add a note to a case

Create Case

Manually create a compliance case. Auto-created cases use the same structure. Request Body

Field	Type	Required	Description
`type`	`string`	✅	Case type (see table below)
`priority`	`string`	✅	`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`
`title`	`string`	✅	Short summary
`description`	`string`	✅	Detailed explanation
`relatedTransactionId`	`string`		UUID of triggering transaction
`relatedKycApplicationId`	`string`		UUID of related KYC application
`tags`	`string[]`		Labels for categorization

Case Types

Type	When It’s Created
`SUSPICIOUS_TRANSACTION`	Transaction BLOCKED by screening
`AML_ALERT`	Transaction ESCALATED
`SANCTIONS_HIT`	Sanctions list match detected
`PEP_MATCH`	Politically Exposed Person matched
`FRAUD_ALERT`	Behavioral anomaly detected
`KYC_REVIEW`	KYC verification issue
`REGULATORY_INQUIRY`	Manual regulatory investigation
`BEHAVIORAL_ANOMALY`	Device/velocity anomaly flagged

Example Request

curl -X POST /v1/cases \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SUSPICIOUS_TRANSACTION",
    "priority": "HIGH",
    "title": "Large cash deposit -possible structuring",
    "description": "Customer made 4 deposits totaling ₦4.8M in 3 hours",
    "relatedTransactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
    "tags": ["structuring", "cash"]
  }'

const response = await fetch("/v1/cases", {
  method: "POST",
  headers: {
    Authorization: "Bearer <access_token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "SUSPICIOUS_TRANSACTION",
    priority: "HIGH",
    title: "Large cash deposit -possible structuring",
    description: "Customer made 4 deposits totaling ₦4.8M in 3 hours",
    relatedTransactionId: "fae50ecb-d997-4700-bae7-49650678bb06",
    tags: ["structuring", "cash"],
  }),
});
const result = await response.json();

import requests

response = requests.post(
    "/v1/cases",
    headers={
        "Authorization": "Bearer <access_token>",
        "Content-Type": "application/json"
    },
    json={
        "type": "SUSPICIOUS_TRANSACTION",
        "priority": "HIGH",
        "title": "Large cash deposit -possible structuring",
        "description": "Customer made 4 deposits totaling ₦4.8M in 3 hours",
        "relatedTransactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
        "tags": ["structuring", "cash"]
    }
)
result = response.json()

Example Response -201 Created

{
  "success": true,
  "data": {
    "id": "case_12345abcde",
    "caseNumber": "CASE-2026-00001",
    "type": "SUSPICIOUS_TRANSACTION",
    "priority": "HIGH",
    "title": "Large cash deposit -possible structuring",
    "description": "Customer made 4 deposits totaling ₦4.8M in 3 hours",
    "status": "OPEN",
    "assignedTo": null,
    "relatedTransactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
    "relatedKycApplicationId": null,
    "tags": ["structuring", "cash"],
    "resolvedAt": null,
    "createdAt": "2026-05-16T14:30:00Z",
    "updatedAt": "2026-05-16T14:30:00Z"
  }
}

List Cases

Retrieve cases with powerful filtering options. Query Parameters

Parameter	Type	Default	Description
`status`	`string`	-	`OPEN`, `IN_PROGRESS`, `PENDING_REVIEW`, `ESCALATED`, `RESOLVED_TRUE_POSITIVE`, `RESOLVED_FALSE_POSITIVE`, `CLOSED`
`type`	`string`	-	Filter by case type
`priority`	`string`	-	`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`
`assigneeId`	`string`	-	Filter by assigned user
`page`	`integer`	`1`	Page number
`limit`	`integer`	`20`	Items per page

Example Request

curl -X GET "/v1/cases?status=OPEN&priority=CRITICAL&page=1&limit=20" \
  -H "Authorization: Bearer <access_token>"

Example Response -200 OK

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "case_12345abcde",
        "caseNumber": "CASE-2026-00001",
        "type": "SUSPICIOUS_TRANSACTION",
        "priority": "HIGH",
        "title": "Large cash deposit -possible structuring",
        "status": "OPEN",
        "assignedTo": null,
        "tags": ["structuring", "cash"],
        "resolvedAt": null,
        "createdAt": "2026-05-16T14:30:00Z",
        "updatedAt": "2026-05-16T14:30:00Z",
        "assignee": null
      }
    ],
    "total": 15,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

Get Case Detail

Retrieve a case including its full timeline history and related transaction. Path Parameters

Parameter	Type	Description
`id`	`string`	Case UUID

Example Request

curl -X GET /v1/cases/case_12345abcde \
  -H "Authorization: Bearer <access_token>"

Example Response -200 OK

{
  "success": true,
  "data": {
    "id": "case_12345abcde",
    "caseNumber": "CASE-2026-00001",
    "type": "SUSPICIOUS_TRANSACTION",
    "priority": "HIGH",
    "title": "Large cash deposit -possible structuring",
    "description": "Customer made 4 deposits totaling ₦4.8M in 3 hours",
    "status": "OPEN",
    "assignedTo": null,
    "relatedTransactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
    "relatedKycApplicationId": null,
    "tags": ["structuring", "cash"],
    "resolvedAt": null,
    "createdAt": "2026-05-16T14:30:00Z",
    "updatedAt": "2026-05-16T14:30:00Z",
    "assignee": null,
    "relatedTransaction": {
      "id": "fae50ecb-d997-4700-bae7-49650678bb06",
      "externalId": "TXN-0791-389803",
      "amount": "5000000",
      "currency": "NGN",
      "senderName": "John Doe",
      "verdict": {
        "outcome": "REVIEW",
        "riskLevel": "MEDIUM",
        "aggregateScore": 32,
        "totalLatencyMs": 13447
      }
    },
    "timeline": [
      {
        "id": "evt_001",
        "caseId": "case_12345abcde",
        "eventType": "CASE_CREATED",
        "actorId": "550e8400-e29b-41d4-a716-446655440000",
        "description": "Case created manually",
        "previousValue": null,
        "newValue": null,
        "metadata": null,
        "createdAt": "2026-05-16T14:30:00Z",
        "actor": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "email": "officer@bank.com",
          "firstName": "Jane",
          "lastName": "Smith"
        }
      }
    ]
  }
}

Update Case Status

Move a case through its lifecycle. Include a resolution note when closing. Path Parameters

Parameter	Type	Description
`id`	`string`	Case UUID

Request Body

Field	Type	Required	Description
`status`	`string`	✅	New status
`resolutionNote`	`string`		Required when resolving or closing

Example Request

curl -X PATCH /v1/cases/case_12345abcde/status \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "IN_PROGRESS"
  }'

Example Response -200 OK

{
  "success": true,
  "data": {
    "id": "case_12345abcde",
    "caseNumber": "CASE-2026-00001",
    "type": "SUSPICIOUS_TRANSACTION",
    "priority": "HIGH",
    "title": "Large cash deposit -possible structuring",
    "status": "IN_PROGRESS",
    "assignedTo": null,
    "relatedTransactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
    "relatedKycApplicationId": null,
    "tags": ["structuring", "cash"],
    "resolvedAt": null,
    "createdAt": "2026-05-16T14:30:00Z",
    "updatedAt": "2026-05-16T16:00:00Z"
  }
}

Status transitions are validated. You cannot jump from OPEN directly to CLOSED without passing through the required intermediate states.

Assign Case

Assign a case to a specific compliance officer. Path Parameters

Parameter	Type	Description
`id`	`string`	Case UUID

Request Body

Field	Type	Required	Description
`assigneeId`	`string`	✅	User UUID to assign

Example Request

curl -X PATCH /v1/cases/case_12345abcde/assign \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "assigneeId": "550e8400-e29b-41d4-a716-446655440000"
  }'

Example Response -200 OK

{
  "success": true,
  "data": {
    "id": "case_12345abcde",
    "caseNumber": "CASE-2026-00001",
    "type": "SUSPICIOUS_TRANSACTION",
    "priority": "HIGH",
    "title": "Large cash deposit -possible structuring",
    "status": "OPEN",
    "assignedTo": "550e8400-e29b-41d4-a716-446655440000",
    "relatedTransactionId": "fae50ecb-d997-4700-bae7-49650678bb06",
    "relatedKycApplicationId": null,
    "tags": ["structuring", "cash"],
    "resolvedAt": null,
    "createdAt": "2026-05-16T14:30:00Z",
    "updatedAt": "2026-05-16T16:15:00Z"
  }
}

Add Note

Append an investigation note to a case. This creates a timeline event. Path Parameters

Parameter	Type	Description
`id`	`string`	Case UUID

Request Body

Field	Type	Required	Description
`content`	`string`	✅	Note text

Example Request

curl -X POST /v1/cases/case_12345abcde/notes \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Spoke with customer. Provided source of funds documentation."
  }'

Example Response -201 Created

{
  "success": true,
  "data": {
    "id": "evt_002",
    "caseId": "case_12345abcde",
    "eventType": "NOTE_ADDED",
    "actorId": "550e8400-e29b-41d4-a716-446655440000",
    "description": "Spoke with customer. Provided source of funds documentation.",
    "previousValue": null,
    "newValue": null,
    "metadata": null,
    "createdAt": "2026-05-16T17:00:00Z"
  }
}

Overview

Core Concepts

Features

Modules

API Reference

Case Management

Overview

Common Workflows

Permissions

Case Lifecycle

Endpoints

Create Case

List Cases

Get Case Detail

Update Case Status

Assign Case

Add Note

​Overview

​Common Workflows

​Permissions

​Case Lifecycle

​Endpoints

​Create Case

​List Cases

​Get Case Detail

​Update Case Status

​Assign Case

​Add Note

Overview

Common Workflows

Permissions

Case Lifecycle

Endpoints

Create Case

List Cases

Get Case Detail

Update Case Status

Assign Case

Add Note