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

# Client Management

> Comprehensive guide to managing your client portfolio in Stanna

## Overview

Client management is the heart of Stanna. Every client in your portfolio gets a detailed profile that tracks interactions, sentiment, revenue, and relationship health automatically.

## Client Portfolio Overview

Your main client list provides a comprehensive, sortable view of your entire portfolio. Instantly see health scores, sentiment indicators, MRR, last contact dates, and CSM assignments—all with smart filtering and visual status indicators.

<Frame caption="Modern client portfolio with health scoring, sentiment tracking, and smart filters">
  <img src="https://mintcdn.com/stanna/E1ghVFEb9ye75tAS/images/client-portfolio-modern.svg?fit=max&auto=format&n=E1ghVFEb9ye75tAS&q=85&s=d3452ae9c1967672ef971fad773822fb" alt="Client portfolio showing health scores, sentiment emojis, filtering, and at-risk client highlighting" width="1400" height="900" data-path="images/client-portfolio-modern.svg" />
</Frame>

### Portfolio Statistics

The header displays key metrics:

* **Total active clients** (excluding hidden clients)
* **At-risk clients** (health score ≤ 40 by default)
* **Stale contacts** (no interaction in 14+ days by default)
* **Excluded clients** (hidden from main metrics)

### Smart Filtering

Filter clients by category:

* **Active Clients**: All non-excluded clients (default view)
* **At Risk**: Clients with health scores below your risk threshold
* **Stale**: Clients with no recent contact (configurable days)
* **Excluded**: Clients hidden from main portfolio metrics

## Individual Client Profiles

Each client gets a dedicated profile page with detailed health tracking, interaction timeline, and stakeholder management.

<Frame caption="Example client profile showing health score, MRR, and recent interactions">
  <img src="https://mintcdn.com/stanna/SdKdRhhdoh8SPo6O/images/client-profile-snippet.svg?fit=max&auto=format&n=SdKdRhhdoh8SPo6O&q=85&s=f0dd6dabd207579fbf8e38bcbe8fa5b9" alt="Client profile page showing health score of 92, MRR details, and interaction timeline" width="800" height="650" data-path="images/client-profile-snippet.svg" />
</Frame>

## Client Profiles

Each client profile contains:

### Basic Information

* **Company Name & Domain**: Primary identifiers with favicon display
* **MRR (Monthly Recurring Revenue)**: Current subscription value in CAD
* **CSM Owner**: Assigned customer success manager
* **Exclusion Status**: Whether client is excluded from portfolio metrics
* **Tags**: Custom categorization labels

### Health Metrics

* **Sentiment Score**: AI-powered relationship health (0-100) with color-coded badges
* **Last Interaction**: Most recent touchpoint with relative time display (e.g., "5d ago")
* **Renewal Date**: Next contract milestone with formatted dates
* **Score Attribution**: Explanations for health score changes
* **Historical Tracking**: Score changes over time

## Adding Clients

<Tabs>
  <Tab title="Onboarding Flow">
    1. Navigate to **Clients** in the main menu
    2. Click **Add Clients** button
    3. This redirects to `/onboarding` for the complete setup process
    4. Follow the onboarding wizard to add clients and configure integrations
  </Tab>

  <Tab title="CSV Export/Import">
    Current clients can be exported to CSV:

    1. Go to **Clients** page
    2. Apply any filters you want
    3. Click **Export CSV** button
    4. Download includes: name, domain, score, lastInteraction, mrr, renewalDate, owner
  </Tab>

  <Tab title="Integration Sync">
    Clients automatically sync from connected integrations:

    * **Google Workspace**: Gmail contacts and email interactions
    * **HubSpot**: Companies and contacts with activity sync
    * **Intercom**: Companies with conversation history

    All integrations use OAuth2 authentication and sync automatically.
  </Tab>
</Tabs>

## Client Health Scoring

Stanna automatically calculates a health score (0-100) based on:

<AccordionGroup>
  <Accordion title="Interaction Patterns" icon="comments">
    * Frequency of communications
    * Response times from client
    * Types of interactions (support vs. strategic)
  </Accordion>

  <Accordion title="Sentiment Analysis" icon="heart">
    * Email tone analysis
    * Support ticket sentiment
    * Meeting notes sentiment
  </Accordion>

  <Accordion title="Engagement Metrics" icon="chart-line">
    * Product usage (if integrated)
    * Meeting attendance
    * Response to outreach
  </Accordion>

  <Accordion title="Business Indicators" icon="dollar-sign">
    * Payment history
    * Renewal timing
    * Expansion opportunities
  </Accordion>
</AccordionGroup>

### Health Score Ranges

* **🔴 0-40**: At Risk - Immediate attention needed
* **🟡 41-70**: Healthy - Monitor regularly
* **🟢 71-100**: Thriving - Expansion opportunity

## Managing Client Data

### Editing Client Information

1. Click on any client name to open their profile
2. Click the **Edit** button in the top right
3. Update any field and click **Save**

### Client Exclusion

Exclude clients from portfolio metrics without deleting them:

1. Find the client in your client list
2. Look for the "Excluded" badge on excluded clients
3. Use the **Excluded** tab to view all excluded clients
4. Use the API endpoint `POST /api/clients/:id/exclude` to toggle exclusion status

### Search and Sorting

Advanced search and sort capabilities:

* **Search**: Type to search by client name or domain (use `⌘K` keyboard shortcut)
* **Sort by**: Name, Health Score, Last Contact, MRR, Renewal Date
* **Risk Threshold**: Adjust what score is considered "at risk" (default ≤40)
* **Stale Days**: Configure how many days without contact is considered "stale" (default ≥14)
* **Pagination**: 25 clients per page with navigation controls

## Client Interactions

### Viewing Interaction History

Each client profile shows a complete timeline of interactions:

* **Emails**: Sent and received communications
* **Support Tickets**: Help desk interactions
* **Meetings**: Calendar events and notes
* **Phone Calls**: Logged conversations

### Viewing Interaction History

Detailed interaction tracking from integrated platforms:

* **Email interactions**: From Gmail integration with sentiment analysis
* **Support conversations**: From Intercom integration
* **HubSpot activities**: Contact and company interactions
* **Score attribution**: See why health scores changed

### Manual Score Attribution

Provide context for health score changes:

1. Open any client profile
2. Navigate to the attributions section
3. Use the `POST /api/clients/:id/attribute` endpoint to add manual explanations
4. Track why scores increased or decreased

<Info>
  **Pro Tip**: Add context to manual interactions to improve sentiment analysis accuracy. Include outcomes and next steps.
</Info>

## Stakeholder Management

Stanna includes a dedicated stakeholder system for tracking multiple contacts within each client organization:

### Stakeholder Features

* Individual stakeholder records linked to clients
* Email-based stakeholder identification from interactions
* Automatic stakeholder discovery from Gmail and other integrations
* Stakeholder-specific interaction history

### Accessing Stakeholder Data

Stakeholder information is available through the client profile and API endpoints. The system automatically identifies stakeholders from email communications and integrates them into the client relationship view.

## Client Management Features

### Task Management

Track action items and follow-ups for each client:

* Create client-specific tasks with due dates
* Mark tasks as complete with timestamps
* View all tasks across your portfolio
* API endpoints: `GET/POST /api/clients/:id/tasks`

### Upcoming Events

Track important milestones and deadlines:

* Renewal dates and contract milestones
* QBR (Quarterly Business Review) scheduling
* Launch dates and implementation milestones
* Custom event types for your business needs
* API endpoints: `GET/POST /api/clients/:id/upcoming`

### Tag System

Organize clients with custom labels:

* Apply multiple tags per client
* Use tags for categorization and filtering
* API endpoint: `POST /api/clients/:id/tags`

## Best Practices

<CardGroup cols={2}>
  <Card title="Regular Reviews" icon="calendar">
    Schedule weekly reviews of your client portfolio to identify trends and risks early.
  </Card>

  <Card title="Accurate Data" icon="check-circle">
    Keep client information current, especially MRR and renewal dates for accurate forecasting.
  </Card>

  <Card title="Stakeholder Mapping" icon="users">
    Maintain complete stakeholder lists with influence levels for effective relationship management.
  </Card>

  <Card title="Interaction Logging" icon="pencil">
    Log all meaningful interactions to maintain complete relationship context.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Client not syncing from integration">
    * Check integration status at `/api/integrations/status`
    * Verify OAuth tokens are valid and not expired
    * Manually trigger sync: `POST /api/integrations/google/sync`, `/hubspot/sync`, or `/intercom/sync`
    * Check data ingestion status at `/api/ingest/status`
  </Accordion>

  <Accordion title="Incorrect health score">
    * Review recent interactions for sentiment accuracy
    * Add manual interactions with correct sentiment
    * Contact support if scores remain consistently wrong
  </Accordion>

  <Accordion title="Missing client data">
    * Check if data exists in the source system
    * Verify field mapping in integration settings
    * Manually add missing information if needed
  </Accordion>
</AccordionGroup>