---
title: "Home \"Insights\" card (top active recommendations)"
method: GET
path: "/companies/{companyId}/insights/home"
tags: ["Overview"]
---

# Home "Insights" card (top active recommendations)

`GET /companies/{companyId}/insights/home`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/companies/{companyId}/insights/home`
- Auth: HTTP bearer

Returns the Home "Insights" card: the top 5 active, non-dismissed, non-suppressed recommendations (engine ranking, presented newest first), gated by the insights-readiness rule — `available: false` with the unmet readiness-requirement id as `reason` until the books support trustworthy output. Recommendations are company-scoped facts today: an `entityId` is honored only when it is the company's ONLY non-group legal entity; otherwise `entity_scope_unavailable` is reported rather than silently company-widening.

## Query parameters

- `entityId` string, uuid

## Response `200`

Home insights payload

- HomeInsightsResponse
  - `success` true, required
  - `data` HomeInsightsData, required
    - `available` boolean, required
    - `reason` 'last_n_months_closed' | 'entity_scope_unavailable' | 'not_ready': Present only when available is false. last_n_months_closed: the insights-readiness gate's unmet requirement (recent months not closed). entity_scope_unavailable: an entityId was given but the company-wide recommendations cannot be honestly attributed to it (it is not the company's only non-group legal entity). not_ready: defensive fallback when readiness reports not-ready without naming a requirement.
    - `items` HomeInsightItem[], required: Empty when available is false; newest first.
      - `id` string, uuid, required
      - `category` string, required
      - `headline` string, required
      - `detail` string, required
      - `generatedAt` string, date-time, required: ISO timestamp the recommendation was generated.

## Other responses

- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `422`: Request failed validation
- `503`: The legal-entity scope authority could not be read

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)