Case Management

Investigation workflow for compliance cases — from alert escalation through SAR determination and filing.

Overview

Cases are created when an alert is escalated (disposition of true_positive with escalate_to_case: true) or manually by a compliance analyst. Each case tracks the full investigation lifecycle: assignment, evidence gathering, status transitions, investigator notes, and SAR determination.

Case Lifecycle

Cases follow a defined status workflow. Each transition is recorded in the audit trail with the acting user and timestamp.

  open
    |
    v
  investigating
    |
    v
  determination
    |
    +---> filing ---> filed       (SAR required)
    |
    +---> no_sar                  (SAR not warranted)
    |
    +---> closed                  (duplicate or insufficient evidence)

Status	Description
`open`	Case created, awaiting investigator assignment
`investigating`	Investigator assigned, active evidence gathering
`determination`	Investigation complete, SAR filing decision pending
`filing`	SAR determined necessary, XML generation and validation in progress
`filed`	SAR submitted to FinCEN BSA E-Filing system
`no_sar`	Investigation concluded, SAR not warranted
`closed`	Case closed — duplicate, insufficient evidence, or administrative closure

List Cases

Returns all cases for an entity. Filter by status, assigned investigator, or date range.

curl "https://api.overvoid.io/v1/onboarding/entities/{entity_id}/cases?status=investigating&limit=20&offset=0" \
  -H "Authorization: Bearer cusd_test_YOUR_KEY"

Query parameters:

Param	Type	Description
`status`	string	Filter by case status
`assigned_to`	string	Filter by assigned investigator email
`from_date`	ISO 8601	Cases created after this date
`to_date`	ISO 8601	Cases created before this date
`limit`	int	Max results (default 20, max 100)
`offset`	int	Pagination offset

Response:

{
  "cases": [
    {
      "case_id": "case_01HXZ8B4P7Q...",
      "entity_id": "ent_01HXYZ...",
      "status": "investigating",
      "priority": "high",
      "assigned_to": "analyst@overvoid.io",
      "alert_ids": ["alt_01HXY9K3M2N..."],
      "created_at": "2026-03-21T09:15:00Z",
      "updated_at": "2026-03-21T10:30:00Z",
      "summary": "Structuring pattern — 3 transactions totaling $29,500 below CTR threshold"
    }
  ],
  "total": 3,
  "limit": 20,
  "offset": 0
}

Get Case Detail

Retrieve full case details including linked alerts, investigation comments, status history, and SAR filing status.

curl https://api.overvoid.io/v1/onboarding/entities/{entity_id}/cases/{case_id} \
  -H "Authorization: Bearer cusd_test_YOUR_KEY"

{
  "case_id": "case_01HXZ8B4P7Q...",
  "entity_id": "ent_01HXYZ...",
  "status": "investigating",
  "priority": "high",
  "assigned_to": "analyst@overvoid.io",
  "alert_ids": ["alt_01HXY9K3M2N..."],
  "created_at": "2026-03-21T09:15:00Z",
  "updated_at": "2026-03-22T16:45:00Z",
  "summary": "Structuring pattern — 3 transactions totaling $29,500 below CTR threshold",
  "comments": [
    {
      "comment_id": "cmt_01HXZ9C5R8S...",
      "author": "analyst@overvoid.io",
      "content": "Reviewed transaction history. Pattern consistent with intentional structuring to avoid CTR filing. Customer has 7 similar transactions in past 30 days.",
      "created_at": "2026-03-21T11:00:00Z"
    }
  ],
  "status_history": [
    { "status": "open", "changed_at": "2026-03-21T09:15:00Z", "changed_by": "system" },
    { "status": "investigating", "changed_at": "2026-03-21T10:30:00Z", "changed_by": "analyst@overvoid.io" }
  ],
  "sar_filing": null
}

Assign Investigator

Assign or reassign an investigator to a case. This also transitions the case from open to investigating if not already in that status.

curl -X POST https://api.overvoid.io/v1/onboarding/entities/{entity_id}/cases/{case_id}/assign \
  -H "Authorization: Bearer cusd_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assigned_to": "senior-analyst@overvoid.io"
  }'

{
  "case_id": "case_01HXZ8B4P7Q...",
  "status": "investigating",
  "assigned_to": "senior-analyst@overvoid.io",
  "updated_at": "2026-03-22T08:00:00Z"
}

Transition Case Status

Move a case to the next status in the lifecycle. Invalid transitions return 422.

curl -X POST https://api.overvoid.io/v1/onboarding/entities/{entity_id}/cases/{case_id}/status \
  -H "Authorization: Bearer cusd_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "determination",
    "reason": "Investigation complete. Evidence supports intentional structuring. Recommending SAR filing."
  }'

Request body:

Field	Type	Description
`status`	string	Target status (must be a valid transition from current status)
`reason`	string	Reason for the status change (required)

Valid transitions:

From	To
`open`	`investigating`, `closed`
`investigating`	`determination`, `closed`
`determination`	`filing`, `no_sar`, `closed`
`filing`	`filed`

{
  "case_id": "case_01HXZ8B4P7Q...",
  "status": "determination",
  "previous_status": "investigating",
  "reason": "Investigation complete. Evidence supports intentional structuring. Recommending SAR filing.",
  "changed_by": "senior-analyst@overvoid.io",
  "updated_at": "2026-03-23T14:00:00Z"
}

Add Investigation Comment

Add an investigation note to a case. Comments form the evidence trail and are included in SAR narrative generation.

curl -X POST https://api.overvoid.io/v1/onboarding/entities/{entity_id}/cases/{case_id}/comment \
  -H "Authorization: Bearer cusd_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Contacted customer regarding transaction pattern. Customer unable to provide satisfactory business justification for sub-threshold structuring. Customer stated transactions were for vendor payments but vendor addresses are unregistered personal wallets."
  }'

{
  "comment_id": "cmt_01HXZ9D6T9U...",
  "case_id": "case_01HXZ8B4P7Q...",
  "author": "senior-analyst@overvoid.io",
  "content": "Contacted customer regarding transaction pattern. Customer unable to provide satisfactory business justification for sub-threshold structuring. Customer stated transactions were for vendor payments but vendor addresses are unregistered personal wallets.",
  "created_at": "2026-03-22T15:30:00Z"
}