Case Management

🚧

Transaction Monitoring in the Lithic Dashboard is Generally Available (GA). The public API spec for these endpoints is in progress and will launch shortly in beta; endpoint names used below are descriptive placeholders and will be linked to formal API reference pages once published. Enum values, request and response shapes, and webhook events are also subject to change during the API beta period.

Overview

A case is the working record for an investigation. When a monitoring rule opens a case, Lithic creates a single record scoped to one entity, attaches the triggering transaction(s), and routes the case to a queue where an analyst picks it up.

Cases can also be created directly via the API or the Lithic Dashboard for investigations that originate outside the rules engine, such as a manual escalation from your support team.

Every case has a unique token, a queue that determines where it surfaces in the dashboard, a status that drives the analyst workflow, and an entity under review (a card or account). Optional parameters include assignee, priority, sla_deadline, tags, rule_token, and resolution. Sub-resources cover transactions, cards, the activity log, comments, and file attachments. Account context is joinable through the Accounts API.

Lifecycle

Cases move through six statuses:

The diagram below shows the recommended workflow. The status transitions table further down lists every legal transition the API accepts.

stateDiagram-v2
    direction TB
    [*] --> OPEN: Case created
    OPEN --> ASSIGNED: Analyst takes the case
    ASSIGNED --> IN_REVIEW: Investigation starts
    IN_REVIEW --> ESCALATED: Needs oversight
    ESCALATED --> IN_REVIEW: Returned for review
    IN_REVIEW --> RESOLVED: Resolution recorded
    ESCALATED --> RESOLVED: Resolution recorded
    RESOLVED --> CLOSED: Finalized
    CLOSED --> [*]

📘

The status ESCALATED is an in-flight state during the investigation, used when the case needs additional review beyond the assignee. The resolution outcome ESCALATED_EXTERNAL (described below) is different. It indicates the case was handed off to an external party (such as law enforcement or a sponsor bank) when the case was closed.

The status transitions shown above describe the recommended workflow. The API accepts status updates without enforcing a fixed transition matrix today; treat the diagram as a workflow guide rather than a guardrail. Always provide resolution and resolution_notes when moving a case to RESOLVED or CLOSED so the activity log records the outcome.

Transaction collection

A case in OPEN is collecting: when the rule that opened the case matches again on the same entity, the new transaction is appended to the case instead of opening a duplicate. Collection stops once the case leaves OPEN, for example when it is assigned to a transaction monitoring analyst. From that point forward, subsequent transactions from the same rule on the same entity start a fresh evaluation window once the existing case is finalized.

The pending_transactions parameter on the case object reflects whether the case is still resolving its initial transaction scope. A case created against a filtered interval (see Create a case) flips pending_transactions to false once Lithic finishes resolving the matching transactions asynchronously. This is independent of the collection lifecycle described above.

Assigning a case

Assigning a case is a two-step operation today: set the assignee parameter and update the status to ASSIGNED in the same request. The API does not automatically transition status when assignee is set on its own. Setting both together stops transaction collection and records both an ASSIGNED_TO and a STATUS event in the activity log.

Queues

Queues group cases by team, product line, or risk category. Every case belongs to exactly one queue. Queues are configured before they are referenced by rules and are managed via the Queues API or the Lithic Dashboard.

Each queue has a name (unique within your program), an optional description, a case_counts summary that breaks down current case volume by status, and standard created, updated, and token parameters. Creating or renaming a queue with a name that is already in use returns a 409 Conflict.

📘

Most programs start with one or two queues (for example, Fraud Monitoring and AML Review) and add more as their operation grows. There is no functional limit on the number of queues that can be created.

Resolution outcomes

When a case transitions to RESOLVED or CLOSED, the analyst records a resolution and resolution_notes. The outcome captures the determination so rule performance can be audited and rules tuned over time.

Working with cases

Create a case

Most cases are created automatically by monitoring rules. To create a case manually, use the Create Case endpoint or the Lithic Dashboard with a queue token, an entity, and a direct transaction reference.

{
  "queue_token": "9e1d4d4e-3e2f-4d72-8a39-ec0e0e7fef94",
  "title": "Manual escalation from support",
  "priority": "HIGH",
  "entity": {
    "entity_type": "CARD",
    "entity_token": "cbab2546-b597-4b17-903e-3e392c10ed64"
  },
  "transaction_scopes": [
    {
      "type": "TRANSACTION",
      "transaction_token": "4a2dba2f-729a-496b-8943-ec11b4768e3e",
      "card_token": "cbab2546-b597-4b17-903e-3e392c10ed64",
      "account_token": "54af6161-d544-4d92-b482-2f96814f438c",
      "transaction_created_at": "2026-05-01T10:30:00Z"
    }
  ]
}

Additional transactions can be appended to an existing case later via the Append Case Transactions endpoint or the Lithic Dashboard. The response contains the appended transaction_token; the append also produces an activity event. Appending transactions to a case that has left OPEN is allowed (for example, to backfill context during an investigation); it does not reopen the case for normal collection.

List, filter, and sort cases

The List Cases endpoint returns a paginated list. Filter by queue_token, status, assignee, rule_token, tags, transaction_token, card_token, account_token, or entity_token. Standard cursor pagination (starting_after, ending_before, page_size) applies.

Sort with the sort_by query parameter. Cursor pagination preserves the chosen order across pages.

Update a case

The Update Case endpoint accepts a partial update. Common transitions:

• To assign a case, set assignee and status to ASSIGNED in the same request to take ownership and stop transaction collection. The change records two activity events, one ASSIGNED_TO for the assignee parameter and one STATUS for the status transition.
• To progress the investigation, update status to IN_REVIEW when work starts, or ESCALATED if additional oversight is needed.
• To resolve, set status to RESOLVED or CLOSED and include resolution and resolution_notes.

📘

PATCH semantics for title, assignee, and sla_deadline are three-way: omit the parameter to leave it unchanged, set it to a value to update, or explicitly set it to null to clear it.

Each update is recorded as an activity event with the parameter that changed, the previous and new values, and the actor.

List flagged transactions

The List Case Transactions endpoint returns the transactions collected onto the case, paginated. The response includes any tags applied during monitoring evaluation with the explanation that the rule recorded.

To inspect a broader baseline for the same entity (for example, six months of history on the card to compare against), use the existing Transactions API filtered by the card or account token. Lithic does not duplicate that data onto the case.

Inspect the involved cards

The List Case Cards endpoint returns each unique card involved in the case's flagged transactions, with a per-card transaction count. To inspect account context, use the account_token on each flagged transaction (or the case's entity, if it is account-scoped) to call the Accounts API for full holder detail.

Comments

Analysts add comments to document findings, hypotheses, or handoff notes.

• The Add Comment endpoint appends a new comment to the case.
• The Edit Comment endpoint edits an existing comment. The activity log retains the edit history.
• The Delete Comment endpoint removes a comment. The activity log retains the deletion record.

File attachments

Cases support file attachments for supporting documentation: investigation reports, screenshots, sanctions checks, and so on.

The upload flow uses a presigned URL:

1. Call the Upload File endpoint with the file name. Lithic returns a file token, a presigned upload URL, and a PENDING file status.
2. PUT the file contents to the presigned URL. Set the Content-Type header on the PUT to the file's MIME type; Lithic reads it from the uploaded object during validation.
3. Lithic asynchronously runs a malware scan and validates the content type and size. The file transitions to READY if the checks pass, or REJECTED with a failure_reason if not.
4. Use the List Case Files endpoint to list, or the Get Case File endpoint for a single file with a download URL.
5. Use the Delete Case File endpoint to soft-delete a file from a case. Deleted files no longer appear in list or get responses; the deletion is recorded in the activity log.

Constraints:

Files that move to REJECTED can be re-uploaded against the same file record. Only files that complete validation (transition to READY) produce a FILE entry in the activity log. The failure_reason for rejected files is available on the file resource itself (for example, malware detected, scan failure, invalid MIME type, file too large).

Activity log

Every system action and analyst action produces an entry on the Case Activity endpoint. Entries are returned in chronological order with cursor pagination.

The activity log is append-only. Edits and deletes to comments are recorded as additional log entries; the originals are preserved.

Reference

Case object

Recommended status transitions

The API does not enforce this matrix today. Always provide resolution and resolution_notes when moving a case to RESOLVED or CLOSED.

Next steps

• Transaction Monitoring Rules: Configure tagging and case creation rules.
• Transaction Monitoring: Overview of the end-to-end product.