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

# Follow-ups

> Triage every contact that is due or overdue for a follow-up from one focused hub

The Follow-ups hub (`/follow-ups`) is the single place to work through every contact whose next follow-up date is today or overdue. It pulls from the same data that drives the dashboard Follow-ups panel — contacts assigned to you who have a `nextFollowUpDate` set — but gives you filtering, multi-select, and richer context so you can clear the list in one focused session.

## When to use the hub vs. the dashboard panel

* **Dashboard Follow-ups panel** — A short, prioritized peek (up to 10 contacts) so you can knock out the most urgent follow-ups without leaving your dashboard.
* **Follow-ups hub** — The full backlog (up to 200 contacts), with filters, bulk Snooze/Mark done, and lead quality on every row. Use it for your morning triage or your Sunday sweep.

You can jump from the dashboard panel header into the hub at any time. Use the **Dashboard** link in the hub header to return.

## The follow-up row

Both the dashboard panel and the hub use the same single-row card so the layout is consistent everywhere a follow-up appears:

| Element               | What it shows                                                   |
| --------------------- | --------------------------------------------------------------- |
| **Avatar**            | The contact's initials or photo                                 |
| **Contact name**      | Tap the row to open the contact's profile                       |
| **Reason**            | "Follow-up due today" or "Follow-up overdue by N days"          |
| **Lead quality chip** | Hot, Warm, Cold, or Nurture — pulled from the contact record    |
| **Snooze**            | Inline button — pushes the follow-up out by 3 days              |
| **Mark done**         | Inline button — clears `nextFollowUpDate` and logs the activity |
| **Overflow menu**     | More actions for the contact                                    |

### Visual signals

The row uses two distinct signals so you can tell at a glance why a contact is on the list:

* **Hot lead** — Amber flame icon next to the name. The contact's lead quality is `HOT`, regardless of when the follow-up is due.
* **Overdue** — Red left border on the card. The follow-up date has already passed.

A contact can be both. The list is sorted so hot **and** overdue rows rise to the top, followed by hot-only, then overdue-only, then everything else.

## Filtering

The hub has four filter tabs across the top, each with a live count:

* **All** — Every due or overdue follow-up
* **Overdue** — Follow-up date is before today
* **Due today** — Follow-up date is today
* **Hot** — Contacts whose lead quality is `HOT`

Counts update as you mark contacts done or snooze them — the row leaves the list immediately and the badges shrink.

## Multi-select and bulk actions

To work through follow-ups in batches:

1. Use the checkbox on each row, or **Select all** to grab everything in the current filter.
2. The bulk action bar appears at the bottom of the screen with the count of selected contacts.
3. Choose **Snooze** to push every selected follow-up out by 3 days, or **Mark done** to clear them.
4. Use the **X** to clear your selection without acting.

Bulk actions only affect contacts assigned to you — the API ignores any IDs you don't have an assignment for, so you can't accidentally clear someone else's queue.

## Empty state

When there's nothing left to do, the hub shows an "All caught up" state with a shortcut to **Go to contacts** so you can set follow-up dates on more people. The dashboard panel collapses to a similar empty state.

## API

The hub and the dashboard panel are both powered by `/api/follow-ups/due`. The endpoint is scoped to the current user's assignments and the current organization.

### `GET /api/follow-ups/due`

Returns due and overdue follow-ups, ordered oldest-overdue first.

Query parameters:

* `limit` — Maximum number of contacts to return. Defaults to `10` (used by the dashboard panel). Maximum `200` (used by the hub).

Response:

```json theme={null}
{
  "followUps": [
    {
      "id": "person_123",
      "contactId": "person_123",
      "contactName": "Sarah Lee",
      "reason": "Follow-up overdue by 4 days",
      "suggestedTiming": "Overdue",
      "isHot": true,
      "leadQuality": "HOT",
      "status": "ACTIVE",
      "overdueDays": 4
    }
  ]
}
```

Notable fields:

* `isHot` — `true` when `leadQuality` is `HOT`. Used to render the amber flame.
* `leadQuality` — Raw value (`HOT`, `WARM`, `COLD`, `NURTURE`) for the lead-quality chip.
* `overdueDays` — `0` if due today, otherwise the number of whole days the follow-up is past due.

### `PATCH /api/follow-ups/due`

Marks one or many follow-ups done or snoozed.

```json theme={null}
{
  "personIds": ["person_123", "person_456"],
  "action": "snooze"
}
```

* `personId` *(string)* — Single contact. Used by inline row actions.
* `personIds` *(string\[])* — Multiple contacts. Used by the hub's bulk action bar. Both fields are accepted — send one or the other.
* `action` *(`"done"` | `"snooze"`)* — `"done"` clears `nextFollowUpDate`; `"snooze"` pushes it out by 3 days.

The response includes the number of contacts that were updated:

```json theme={null}
{ "ok": true, "count": 2, "action": "snooze" }
```

IDs that aren't assigned to the calling user are silently dropped. If none of the requested contacts are assigned to you the endpoint returns `404`.

## Related

* [Tasks](/productivity/tasks) — Time-bound to-dos with due dates. Follow-ups are a separate, contact-level cadence.
* [Relationship Pipeline](/crm/relationship-pipeline) — Where you set the cadence that drives `nextFollowUpDate`.
* [AI Assistant](/ai/ai-assistant) — Smart follow-up and next-action suggestions surfaced alongside the hub.