Lookup Reports

Endpoints for end users to look up their own reports. No authentication required.

List Reports

GET /v1/reports/lookup

No permission required (public endpoint)

Query Parameters:

Field	Type	Required	Description
phoneNumber	string	Conditional	Filter by phone number (required unless walletAddress provided)
walletAddress	string	Conditional	Filter by wallet address (required unless phoneNumber provided)
status	string	No	pending, processing, resolved, or dismissed
complaintType	string	No	track_transaction, stolen_funds, or fraud
limit	number	No	Results per page, 1-200 (default 50)
offset	number	No	Pagination offset (default 0)

Example Request:

GET /v1/reports/lookup?phoneNumber=2348012345678&status=pending

Response:

{
  "success": true,
  "data": {
    "reports": [
      {
        "id": 42,
        "reportId": "RPT-7N4VFR",
        "apiKeyId": 7,
        "merchantId": "merchant_001",
        "sessionReference": null,
        "complaintType": "stolen_funds",
        "name": "Adaeze Nwosu",
        "phoneNumber": "2348012345678",
        "walletAddress": "TDrhiGeJ11zNStTLhcJt4CvqSwyUVbHPZR",
        "fraudsterWalletAddress": "TXn9d8f7e6c5b4a3928170fedcba0987654",
        "description": "Funds were sent to the wrong address after a phishing link.",
        "status": "pending",
        "confirmer": null,
        "adminNotes": null,
        "createdAt": "2026-07-29T10:15:00.000Z",
        "updatedAt": "2026-07-29T10:15:00.000Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}

Error Cases:

• Missing both phoneNumber and walletAddress: 400 - At least one of phoneNumber or walletAddress is required

---

Get Single Report

GET /v1/reports/:reportId

No permission required (public endpoint)

Example Request:

GET /v1/reports/RPT-7N4VFR

Response:

{
  "success": true,
  "data": {
    "report": {
      "id": 42,
      "reportId": "RPT-7N4VFR",
      "apiKeyId": 7,
      "merchantId": "merchant_001",
      "sessionReference": null,
      "complaintType": "stolen_funds",
      "name": "Adaeze Nwosu",
      "phoneNumber": "2348012345678",
      "walletAddress": "TDrhiGeJ11zNStTLhcJt4CvqSwyUVbHPZR",
      "fraudsterWalletAddress": "TXn9d8f7e6c5b4a3928170fedcba0987654",
      "description": "Funds were sent to the wrong address after a phishing link.",
      "status": "pending",
      "confirmer": null,
      "adminNotes": null,
      "createdAt": "2026-07-29T10:15:00.000Z",
      "updatedAt": "2026-07-29T10:15:00.000Z"
    }
  }
}

Error Cases:

• Invalid reportId format (must match RPT-XXXXXX): 400 - Invalid report ID format
• Report not found: 404 - Report not found