> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vultlocal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Suspicious Transactions

> List transactions flagged as suspicious

# List Suspicious Transactions

Retrieve transactions flagged as suspicious by the fraud detection system.

## Endpoint

```http theme={null}
GET /api/v1/transactions/suspicious
```

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token (Compliance or Admin JWT)
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number
</ParamField>

<ParamField query="page_size" type="integer" default="20">
  Records per page (max 100)
</ParamField>

<ParamField query="from_date" type="string">
  Start date (YYYY-MM-DD), defaults to 30 days ago
</ParamField>

<ParamField query="to_date" type="string">
  End date (YYYY-MM-DD), defaults to today
</ParamField>

<ParamField query="severity" type="string" default="all">
  Risk level: `low`, `medium`, `high`, `critical`, or `all`
</ParamField>

<ParamField query="status" type="string" default="all">
  Review status: `pending`, `under_review`, `cleared`, `confirmed`, or `all`
</ParamField>

<ParamField query="subscriber_id" type="string">
  Filter by subscriber UUID
</ParamField>

<ParamField query="agent_id" type="string">
  Filter by agent UUID
</ParamField>

<ParamField query="transaction_type" type="string" default="all">
  Transaction type filter
</ParamField>

<ParamField query="min_amount" type="number">
  Minimum amount filter
</ParamField>

<ParamField query="max_amount" type="number">
  Maximum amount filter
</ParamField>

<ParamField query="sort_by" type="string" default="created_at">
  Sort field: `created_at`, `amount`, `severity`, `risk_score`
</ParamField>

<ParamField query="sort_order" type="string" default="desc">
  Sort order: `asc` or `desc`
</ParamField>

## Response

```json theme={null}
{
  "success": true,
  "message": "Suspicious transactions retrieved successfully",
  "data": {
    "transactions": [
      {
        "id": "sus_abc123",
        "transaction_id": "txn_xyz789",
        "type": "transfer_p2p",
        "amount": 500000,
        "risk_score": 85,
        "severity": "high",
        "review_status": "pending",
        "flags": ["unusual_amount", "new_recipient"],
        "suspicious_indicators": [
          "Amount 10x higher than average",
          "First transaction to this recipient"
        ],
        "created_at": "2025-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "page_size": 20,
      "total_records": 45,
      "total_pages": 3,
      "has_next": true,
      "has_previous": false
    },
    "summary": {
      "total_suspicious": 45,
      "pending_review": 20,
      "under_review": 10,
      "cleared": 12,
      "confirmed_fraud": 3
    }
  }
}
```

## Errors

| Code | Description              |
| ---- | ------------------------ |
| 400  | Invalid date format      |
| 401  | Unauthorized             |
| 403  | Insufficient permissions |
| 500  | Internal server error    |


## OpenAPI

````yaml olive-openapi.json GET /transactions/suspicious
openapi: 3.0.0
info:
  description: >-
    API Gateway for OLIVE NFC Card Payment System - Comprehensive payment, card
    management, agent operations, and admin authentication. All /api/v1 routes
    require authentication using either API Key or JWT token.
  title: OLIVE NFC Card Payment API
  termsOfService: http://swagger.io/terms/
  contact:
    name: API Support
    email: support@olive.sl
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://olive-gateway-a6ba.onrender.com/api/v1
security: []
paths:
  /transactions/suspicious:
    get:
      tags:
        - Compliance
      summary: Get suspicious transactions
      description: Retrieve transactions flagged as suspicious by fraud detection system
      parameters:
        - description: Page number
          name: page
          in: query
          schema:
            type: integer
            default: 1
        - description: Records per page (max 100)
          name: page_size
          in: query
          schema:
            type: integer
            default: 20
        - description: Start date (YYYY-MM-DD)
          name: from_date
          in: query
          schema:
            type: string
        - description: End date (YYYY-MM-DD)
          name: to_date
          in: query
          schema:
            type: string
        - description: 'Risk severity: low, medium, high, critical, all'
          name: severity
          in: query
          schema:
            type: string
            default: '"all"'
        - description: 'Review status: pending, under_review, cleared, confirmed, all'
          name: status
          in: query
          schema:
            type: string
            default: '"all"'
        - description: Filter by subscriber ID
          name: subscriber_id
          in: query
          schema:
            type: string
        - description: Filter by agent ID
          name: agent_id
          in: query
          schema:
            type: string
        - description: Transaction type filter
          name: transaction_type
          in: query
          schema:
            type: string
            default: '"all"'
        - description: Minimum amount filter
          name: min_amount
          in: query
          schema:
            type: number
        - description: Maximum amount filter
          name: max_amount
          in: query
          schema:
            type: number
        - description: 'Sort field: created_at, amount, severity, risk_score'
          name: sort_by
          in: query
          schema:
            type: string
            default: '"created_at"'
        - description: 'Sort order: asc, desc'
          name: sort_order
          in: query
          schema:
            type: string
            default: '"desc"'
      responses:
        '200':
          description: Suspicious transactions retrieved
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
      security:
        - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      description: >-
        JWT token from admin login for administrative operations. Format:
        'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
      type: apiKey
      name: Authorization
      in: header

````