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"]
  }'

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

Core Concepts

Features

Modules

API Reference

Documentation Index

​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