Peer Benchmarking API (/api/v1/peer-benchmarking)

NCUA-based credit union peer analysis. Search institutions, compare financial KPIs against peer groups, generate AI-powered insights, and download professional PDF reports.

---

1. Search Institutions

Searches for credit union institutions by name.

• Method: GET
• Endpoint: /api/v1/peer-benchmarking/search
• Authentication: Required (X-API-Key)

Query Parameters

Parameter	Type	Required	Description
q	String	Yes	Search query (min 2 characters)

Response (200 OK):

[
  {
    "cu_number": 12345,
    "cu_name": "EXAMPLE CREDIT UNION",
    "state": "CA"
  }
]

---

2. Get Peer Benchmarking Data

Fetches KPI, loan breakdown, and historical benchmarking data for a specific institution. If no filters are provided, applies "Smart Defaults" based on asset and member size.

• Method: POST
• Endpoint: /api/v1/peer-benchmarking/data
• Authentication: Required (X-API-Key)

Request Body

{
  "cu_number": "12345",
  "filters": {
    "states": ["CA", "NY"],
    "assets": { "min": 0, "max": 50000000 },
    "members": { "min": 0, "max": 5000 },
    "net_worth_ratio": { "min": 0.05, "max": 0.10 },
    "delinquency_rate": { "min": 0.01, "max": 0.05 }
  }
}

Response (200 OK)

{
  "applied_filters": { ... },
  "institution": {
    "cu_number": 12345,
    "cu_name": "EXAMPLE CREDIT UNION",
    "state": "CA",
    "asset_tier": "Tier 1",
    "peer_count": 150,
    "source": "NCUA"
  },
  "latest_kpis": {
    "cycle_date": "2023-12-31T00:00:00.000Z",
    "assets": 10000000,
    "members": 1500,
    "delinquency_pct": 1.5,
    "capital_ratio_pct": 10.2,
    "chargeoff_pct": 0.4,
    "loan_to_asset_pct": 65.0,
    "delinquency_rank": 45,
    "capital_rank": 80,
    "chargeoff_rank": 30,
    "loan_to_asset_rank": 70
  },
  "loan_breakdown": {
    "real_estate_loans": 4000000,
    "auto_loans": 1500000,
    "personal_loans": 500000,
    "business_loans": 400000,
    "credit_card_loans": 100000
  },
  "history": [
    {
      "cycle_date": "2023-03-31T00:00:00.000Z",
      "delinquency_pct": 1.2,
      "peer_avg_delinquency_pct": 1.4
    }
  ]
}

---

3. Get AI Insights

Generates AI-powered strategic insights based on the institution's profile and KPIs.

• Method: POST
• Endpoint: /api/v1/peer-benchmarking/insights
• Authentication: Required (X-API-Key)

Request Body

{
  "institution": { "cu_number": 12345, "cu_name": "EXAMPLE CREDIT UNION", ... },
  "kpis": { "delinquency_pct": 1.5, "capital_ratio_pct": 10.2, ... }
}

---

4. Generate Peer Benchmarking PDF Report

Generate a professional PDF report containing KPIs, peer comparison charts, and AI insights.

• Method: POST
• Endpoint: /api/v1/peer-benchmarking/report
• Authentication: Required

Request Body

{
  "cu_number": "12345",
  "filters": { ... }
}

Response

• Content-Type: application/pdf
• Returns: Binary PDF stream (peer_benchmarking_report_<cu_name>.pdf)

---

Public Routes (Unauthenticated)

These routes expose the same functionality without authentication — intended for shareable links and public reports.

Endpoint	Description
POST /peer-benchmarking/public/data	Same as POST /data
POST /peer-benchmarking/public/insights	Same as POST /insights
POST /peer-benchmarking/public/report	Same as POST /report — returns PDF binary

---

5. Email Public Report

Send a shareable peer benchmarking report link via email.

• Method: POST
• Endpoint: /api/v1/peer-benchmarking/public/email-report
• Authentication: None

Request Body

{
  "email": "recipient@example.com",
  "cu_name": "EXAMPLE CREDIT UNION",
  "cu_number": "12345",
  "report_url": "https://riskinmind.com/report/..."
}

Response

{ "success": true, "message": "Report shared successfully via email" }