# Overview Tab
Source: https://docs.quivly.ai/customer-views/account-tab
The customer overview — a customizable summary of health, revenue, usage, support, calls, and signals, with editable account fields
## Overview
The Overview tab is the default view when opening a customer. It's a customizable canvas of summary sections pulling from every other tab — arrange it once and every customer profile follows the same layout.
***
## Header Fields
The header shows the customer name with **domain** and **LinkedIn** icon links, plus a row of quick-edit fields. By default: **Segment**, **Service Tier**, and **Lifecycle Stage**. Click the header's customize control to show up to 8 fields — any customer field, including custom fields. Fields synced from your CRM, AI-computed, or read-only render as locked pills with a tooltip explaining why.
***
## Summary Sections
A time-range picker (7d / 30d / 90d / MTD / QTD / YTD / custom / all) scopes every metric section. Sections include:
* **Health Score** — current score, trend, risk badge, and history chart (pinned at top)
* **AI Insights** — an AI-written account summary
* **Revenue** — MRR, ARR, outstanding balance, days to renewal (with a warning at ≤30 days)
* **Usage** — the product usage metrics you select for the section, each with value and trend
* **Support** — total and open tickets, average resolution and first response times
* **Calls** — total calls, average duration, average gap, last call
* **Market Signals** — the three most recent signals with sentiment; click through for the full list
* **Projects** — active project status
### Customizing the layout
Click **Customize** to enter edit mode: drag sections to reorder, hide the ones you don't need, and use each section's gear to choose which metrics it shows. Click **Done** to finish. The layout applies across customers.
***
## Account Info Sidebar
A collapsible side panel holds the full editable account record:
* **Editable** — company name, domain, secondary domains, description, LinkedIn, industry, customer since, CSM owner, and editable custom fields
* **Read-only** — fields synced from your CRM (marked with a "syncs from…" tooltip), AI-computed fields, location, employee count, annual revenue, and External ID (copyable)
A search box filters fields, and an **Integration Data** section shows extra attributes from your connected systems.
# Calls Tab
Source: https://docs.quivly.ai/customer-views/calls-tab
Call recordings with AI summaries, sentiment, action items, and a notes system — synced from Fireflies, Fathom, Granola, and other providers
## Overview
The Calls tab shows every recorded call with this customer, synced from your call recording integrations (Fireflies, Fathom, Granola), with AI-generated summaries and a notes system for capturing insights.
***
## Layout
At the top: a metrics grid — **Total Calls**, **Avg Duration**, **Last Call**, **Total Time** — and a **Call Activity heatmap** of the last 12 months, colored by call sentiment.
Below that, a master-detail layout: a searchable list of call cards on the left, and the selected call's detail on the right. Search matches titles, participants, organizers, keywords, topics, summaries, and call type.
***
## Call Details
Selecting a call shows:
* **AI summary** — overview, key points, and meeting type
* **Sentiment** — a score out of 5 with the AI's reasoning
* **Action items** — extracted tasks, with owners where detected
* **Signals** — growth and risk signals spotted in the conversation
* **Topics, keywords, and key quotes**
* **Participants** — attendee names and avatars
* **Watch** — opens the original recording at the provider
Calls still being analyzed show an "Analysis in progress" state.
***
## Notes
Open the **Notes** button on a call to capture insights alongside it.
* **Rich text editor** — formatting, lists, links, and code blocks; **Cmd+Enter** to save
* **@Mentions** — mention teammates, or type `@Quivly` to ask the AI about the call
* **AI Q\&A** — ask questions like "What were the main concerns raised?"; the AI answers from the full transcript and summary, with clickable timestamp references, and you can save the response as a note
* **Prompt templates** — save reusable questions (shared across your organization)
* **Search** — filter notes by content or creator, with inline highlighting
Notes are grouped by date, newest first. You can edit or delete your own notes.
# Custom Views
Source: https://docs.quivly.ai/customer-views/custom-views
Save filtered, sorted, and column-configured versions of the customer list — private or shared with your org
## Overview
A view is a saved snapshot of the customer list: its filters, columns, and sort. Set the list up the way you want, save it as a view, and switch between views from the picker in the header.
Views are **private to you** or **shared with the organization**, grouped as "My views" and "Shared" in the picker.
***
## Creating a View
Apply filters, choose columns, and sort — the live page state is what gets saved.
Open the view picker and choose **Save current state as new view**. Give it a name, pick an icon, and choose visibility: **Private to me** or **Shared with org**.
***
## Editing a View
Edits happen live: open a view, change filters/columns/sort, and **Reset / Save** controls appear while the view has unsaved changes. Save persists the new state; Reset returns to the saved one.
Rename, change the icon, switch visibility, or delete a view from its row menu in the picker.
***
## Default View
Star a view to make it **your** landing view when you open Customers. The star is per user — it doesn't change what teammates see. Open **All Customers** to see the unfiltered list.
***
## Use Cases
| View | Filters | Why |
| ----------------------- | -------------------------------------------- | ----------------------------------------------------- |
| **At-Risk Customers** | Health risk level is "Critical" or "At Risk" | Prioritize outreach to customers most likely to churn |
| **Enterprise Accounts** | Segment is "Enterprise" or "Strategic" | Focus on your highest-value customers |
| **Onboarding** | Lifecycle stage is "Onboarding" | Track new customers through setup |
| **Renewal Pipeline** | Lifecycle stage is "Renewing" | Monitor upcoming renewals |
| **Low Engagement** | Total calls equals 0, Total tickets equals 0 | Find customers with no recent interactions |
For "just my accounts", use the **My Accounts** chip on any view instead of a saved view.
# Customer List
Source: https://docs.quivly.ai/customer-views/customer-list
Browse, filter, and manage all your customers in a customizable table with saved views
## Overview
The Customer List is your central view for managing all customers. It displays data from your connected integrations in a unified, customizable table.
Click **Customers** in the main navigation. The page always opens in a view — your default view, or All Customers.
***
## Table Columns
Default columns include:
| Column | Description |
| --------------------- | --------------------------------------------------- |
| **Customer Name** | Account name with company logo |
| **Domain** | Website domain (clickable link) |
| **MRR** | Monthly recurring revenue |
| **Health Score** | Current score with trend indicator (up/down/stable) |
| **Health Risk Level** | Color-coded risk badge |
| **Lifecycle Stage** | Color-coded stage badge |
| **Segment** | Color-coded segment badge |
| **Calls** | Total call recordings count |
| **Tickets** | Total support tickets count |
| **Signals** | Total market signals count |
Any customer field can be a column — including **custom fields** and **product usage metrics** (with 30d/60d/90d/180d/1y period options and trend indicators).
### Customizing Columns
Two ways:
* **+ Add column** at the end of the table — add an existing attribute, or create a new standard or AI attribute on the spot.
* The **Settings** gear in the header — its **Columns** section toggles and reorders columns.
Columns can be pinned and resized in the table.
***
## Search & Quick Filters
* The search bar finds customers by name or domain.
* The **My Accounts** chip filters to customers where you're the CSM owner.
***
## Filtering
Click the **Filter** control in the header to build filters: pick a field, an operator, and a value. Applied filters show as removable chips above the table. Conditions combine with AND logic.
Operators vary by field type:
| Field Type | Operators |
| ----------- | ----------------------------------------------------------------------------------------------------------- |
| **Text** | is, is not, contains, does not contain, starts with, ends with, is empty, has value |
| **Number** | equals, not equals, greater than, greater than or equal, less than, less than or equal, is empty, has value |
| **Date** | is on, is after, is on or after, is before, is on or before, is empty, has value |
| **Boolean** | is |
| **Select** | is, is not, is one of, is not one of |
***
## Sorting
Click any sortable column header to sort ascending; click again for descending.
***
## Saved Views
Your current filters, columns, and sort can be saved as a named view — see [Custom Views](/customer-views/custom-views).
***
## Adding & Managing Customers
* **Add customer** creates a customer manually.
* Select rows with checkboxes for bulk actions: **delete**, or **assign a CSM** to all selected customers.
* Each row's three-dot menu can remove the customer; clicking the row opens the customer's profile.
# Health Score Tab
Source: https://docs.quivly.ai/customer-views/health-score-tab
View customer health score trends, breakdowns, and configuration history
## Overview
The Health Score Tab displays the customer's current health score, historical trend chart, and detailed score breakdowns by category. Scores range from 0 to 100.
***
## Current Score
The top section shows:
* **Score** - Large numeric display (0-100)
* **Risk level badge** - Color-coded status using your configured buckets (defaults):
* **Healthy** (green) - Low risk
* **Medium** (amber) - Moderate risk
* **At Risk** (orange) - Elevated risk
* **Critical** (rose) - Immediate attention needed
* **Trend indicator** - Points gained or lost since the previous score, with percentage change
* **Progress bar** - Visual bar showing the score position on a 0-100 scale
* **Calculation date** - When the score was last computed
Hover over the score to see the configuration version, exact timestamp, and whether it was triggered manually or on a schedule.
***
## History Chart
A time-series line chart shows health score changes over time.
* **Data points** - Each point displays the score number and is color-coded by value
* **Click a point** to expand the inline score breakdown for that calculation
* **Version markers** - Dashed vertical lines indicate when the health score configuration changed; hover to see the version or config switch
* **Tooltip** - Hover over any point to see the score, risk level, config name and version, which config routed the score (default or segment), date, and trigger type
***
## Score Breakdown
Click any data point on the chart to view how that score was calculated. The breakdown shows:
* **Score and risk level** with the calculation timestamp
* **Quivly's Analysis** - the AI's reasoning about the score
* **Category table** with columns:
* **Category** - The scoring area (e.g., Revenue, Product Usage, Engagement, Support, Market Signals)
* **Score** - Individual category score (0-100)
* **Weight** - How much this category contributes to the total
* **Contribution** - Weighted score value
* Each category expands to show its reasoning and supporting evidence
* **Recommended Actions** - suggested next steps based on the score
* **Total row** - Final calculated score
To review the configuration behind a score, see [version history](/health-scores/version-history) under **Settings → Health Score**.
# Market Signals Tab
Source: https://docs.quivly.ai/customer-views/market-signals-tab
Track external news and market intelligence for your customers
## Overview
The Market Signals Tab displays AI-analyzed market intelligence relevant to each customer, including funding events, leadership changes, industry news, and more.
***
## Search and Filters
Use the controls at the top of the tab to narrow down signals:
* **Search** - Filter by signal title, summary, or tags
* **Sentiment** - Filter by Positive, Negative, or Neutral sentiment
* **Relevance** - Filter by relevance level (High, Medium, Low); the tab shows relevant signals only
***
## Signal Cards
Each market signal is displayed as a card with the following information:
### Title and Summary
The signal headline and a brief AI-generated summary of the event.
### Sentiment
A color-coded badge indicating the signal's sentiment:
* **Positive** (green) - Favorable event (e.g., funding round, expansion)
* **Negative** (red) - Unfavorable event (e.g., layoffs, leadership departure)
* **Neutral** (gray) - Informational event
### Relevance
When a signal is marked as relevant, an indigo-highlighted box shows:
* **Relevance level** - High, Medium, or Low with a visual strength indicator
* **Relevance reason** - AI-generated explanation of why the signal matters for this customer
### Tags and Sources
* **Tags** - Categorization labels (e.g., "AI", "Competitor", "Market Trends")
* **Source links** - Clickable badges linking to the original article or announcement, showing the source domain name
# Revenue Tab
Source: https://docs.quivly.ai/customer-views/revenue-tab
Track recurring revenue, subscriptions, and invoices
## Overview
The Revenue Tab displays billing data from your connected billing provider, including recurring revenue metrics, active and past subscriptions, and a full invoice history.
***
## Key Metrics
Six metric cards are displayed at the top:
| Metric | Description |
| ------------------- | --------------------------------------------------- |
| **MRR** | Monthly recurring revenue from active subscriptions |
| **ARR** | Annual recurring revenue (MRR x 12) |
| **Total Paid** | Sum of all paid invoices |
| **Outstanding** | Unpaid invoice amounts (highlighted in red if > 0) |
| **Days to Renewal** | Time until subscription renewal (amber if overdue) |
| **Renewal Date** | Date when the current subscription period ends |
***
## Subscriptions
### Active Subscriptions
Each active or trialing subscription displays:
* **Name and status** - Subscription description with a color-coded status badge (Active, Trialing, Past Due, Canceled)
* **MRR** - Monthly recurring amount
* **Line items** - Individual products with quantity, unit price, and billing interval
* **Dates** - Start date, renewal date with countdown, and trial end date if applicable
* **Cancellation notice** - Orange warning if the subscription is set to cancel at the end of the billing period
### Past Subscriptions
Canceled and expired subscriptions appear in a separate section below active subscriptions, using the same card layout.
***
## Invoices
Invoices are displayed in a two-panel layout.
### Invoice List
The left panel shows all invoices sorted by date (newest first). Each invoice displays:
* **Invoice number**
* **Status badge** - Paid (green), Open (amber), Draft (gray), Uncollectible/Void (red)
* **Total amount**
* **Due date**
* **Payment timing** - Shows whether payment was early, on time, or late relative to the due date
Click any invoice to view its details in the right panel.
### Invoice Details
The right panel displays the selected invoice with:
* **Status and source system**
* **Total, subtotal, tax, amount paid, and amount remaining**
* **Line items** - Description, billing period, quantity, and amount for each item
* **Dates** - Due date, paid date, billing period, and created date
* **Additional info** - Billing reason, collection method, and payment attempt count (when available)
* **Actions** - Download PDF and view hosted invoice links (when available from your billing provider)
# Support Tab
Source: https://docs.quivly.ai/customer-views/support-tab
View support tickets, resolution metrics, and ticket activity
## Overview
The Support Tab displays support ticket data from your connected support integration. It uses a master-detail layout with summary metrics, a ticket activity heatmap, a searchable ticket list, and a detail panel.
***
## Summary Metrics
Four metric cards are displayed at the top:
| Metric | Description |
| ------------------------- | --------------------------------------- |
| **Total Tickets** | All-time ticket count |
| **Open Tickets** | Tickets with status "open" or "pending" |
| **Avg Resolution Time** | Average time to resolve tickets |
| **Avg 1st Response Time** | Average time to first response |
***
## Ticket Activity Heatmap
A calendar heatmap shows ticket creation volume over the past 12 months. Each day is color-coded by ticket count (lighter to darker blue). Hover over a day to see the count, and click to jump to tickets from that date.
***
## Ticket List
The left panel displays a searchable list of all tickets, sorted newest first.
**Search** filters tickets by subject, requester name, requester email, status, or ticket number.
Each ticket in the list shows:
* **Subject** and **status badge** - Color-coded: New (blue), Open (blue), Pending (amber), Waiting on You (amber), Waiting on Customer (purple), On Hold (slate), Solved (green), Closed (gray), Escalated (rose)
* **Ticket number** and **date**
* **Requester** - Avatar with name
Click a ticket to view its details in the right panel.
***
## Ticket Details
The detail panel shows the full ticket information:
### Header
* Ticket subject, number, and full date/time
* **View** button linking to the ticket in your support system (when available)
### Status and Priority
* **Status badge** - New, Open, Pending, Waiting on You, Waiting on Customer, On Hold, Solved, Closed, or Escalated
* **Priority badge** - Urgent (rose), High (orange), Normal (blue), Low (gray)
* **Channel** - How the ticket was submitted (Slack, Teams, email, chat, form, Discord, WhatsApp, SMS, Telegram, or manual)
### Description
The full ticket description rendered as HTML content.
### Response Metrics
* **First Response** time
* **Resolution Time**
### Additional Information
* **Tags** - Labels attached to the ticket
* **Group** - Support team group
* **Type** - Ticket or Conversation
* **Resolved** - Relative time since resolution
* **CSAT** - Customer satisfaction score (0-100)
The requester (name and avatar) is shown on each ticket in the list.
# Usage Tab
Source: https://docs.quivly.ai/customer-views/usage-tab
Monitor product adoption and user engagement
## Overview
The Usage Tab displays product analytics data from your data warehouse integration, showing how customers adopt and use your product.
***
## Key Metrics
At the top of the Usage Tab, view:
* **Active Users** - DAU, WAU, MAU vs. licensed seats
* **Adoption Score** - Overall product adoption (0-100)
* **Engagement Frequency** - Session frequency and duration
* **Feature Usage** - Core and advanced features in use
* **Usage Trend** - 30-day growth or decline
***
## Usage Health Indicators
* **Healthy** - Active user rate >70%, increasing trend, core features adopted
* **Moderate** - Active user rate 40-70%, flat trend, some features not adopted
* **Low** - Active user rate below 40%, declining trend, significant churn risk
***
## User Activity
View user-level activity:
| Segment | Definition |
| ------------------ | --------------------------------- |
| **Power Users** | Top 10% most active, daily usage |
| **Active Users** | Regular users, 2-3x per week |
| **Casual Users** | Infrequent, less than 1x per week |
| **Inactive Users** | No activity in 30+ days |
***
## Feature Adoption
Track which features customers use:
* **Core Features** - Essential functionality expected in first 30 days
* **Advanced Features** - Power user capabilities
* **Premium Features** - Higher-tier plan features
View adoption status: Adopted (over 50% users), Partial (10-50%), Not Adopted (under 10%).
***
## Usage Trends
Visualize usage patterns:
* Time series showing daily/weekly/monthly trends
* Seasonal patterns and anomalies
* Usage alerts for significant changes
***
## Expansion Indicators
Usage patterns that suggest expansion opportunities:
* Approaching plan limits (users, storage, API calls)
* Interest in premium features
* High engagement with current features
* Team growth at customer company
***
## Churn Risk Indicators
Usage patterns that predict churn:
* Declining usage trend (3+ consecutive weeks)
* Decreasing active users
* Core feature abandonment
* Power users becoming inactive
***
## Next Steps
Link usage to revenue metrics
See how usage impacts health
# Creating Dashboards
Source: https://docs.quivly.ai/dashboards/creating-dashboards
Build and customize dashboards with widgets
## Creating a Dashboard
From the dashboards list page:
* **Create Dashboard** opens a panel with **Library** (pre-built templates), **Saved** (your saved templates), and **Create** (a blank dashboard with a name, description, icon, and entity type).
* **Build with AI** is a separate button that starts a guided wizard: describe what you want, answer a couple of clarifying questions, and the AI generates the dashboard and its widgets.
After creation, you're taken to the dashboard detail page.
***
## Dashboard Settings
Click the settings icon in the toolbar to edit:
* **Name** and **Description**
* **Icon** - Searchable icon picker
* **Starred** - Mark as a favorite for quick access
***
## Adding Widgets
Click **Edit** in the dashboard toolbar.
Click **Add Widget** to open the widget panel. Choose from two tabs:
* **Create** - Build a custom widget using the configuration form
* **Templates** - Browse system and saved widget templates
To build widgets with AI instead, use the dashboard's AI chat panel — describe the widgets you want and it adds them one by one.
Select a chart type and configure the data source, display options, and filters (see below).
Click **Save** to add the widget to your dashboard.
***
## Widget Configuration
### Data Source
* **Entity Type** - Inherited from the dashboard (e.g., customers, contacts, product usage)
* **Measure** - The aggregate operation (Count, Sum, Average, Max, Min, Median, Percentiles, etc.) and the field to aggregate
* **Dimension** - The field to group by, with optional date granularity (day, week, month, quarter, year), sort order, and limit
* **Secondary Dimension** - An optional second grouping field for multi-series charts
### Display Options
Common display options across chart types:
* **Color scheme** - Choose from preset color palettes
* **Labels and legend** - Toggle visibility and legend position
* **Axis labels** - Custom X and Y axis labels
* **Grid lines** - Show or hide
### Chart-Specific Options
* Sparkline toggle (line, area, or bar)
* Number abbreviation (K, M, B)
* Decimal places
* Orientation (vertical or horizontal)
* Color mode (varied colors or single color)
* Grouped or stacked
* Curve style (linear, smooth, step, natural)
* Stacked toggle
* Fill opacity (area charts)
* Gap fill strategy (zero, null, interpolate)
* Arc label position (inside or outside)
* Inner radius for donut effect
* Pad angle between slices
* Column visibility toggles
* Page size
* Sortable, striped, and compact modes
* Markdown content editor
* Text alignment (left, center, right)
* Font size
### Widget Filters
Each widget can have its own filter conditions, independent of dashboard-level filters. Use the **Exclude Filters** toggle to prevent the dashboard's global filters from applying to a specific widget.
***
## Editing Layout
In edit mode, the dashboard uses a 12-column grid layout:
* **Drag widgets** by their header to reposition them
* **Resize widgets** by dragging their corners
* Changes auto-save as you edit
* A status indicator shows "Saving..." and "Saved" in the toolbar
***
## Saving Templates
Save a widget or entire dashboard as a reusable template:
* Widget templates store the full widget configuration for reuse
* Dashboard templates capture all widgets and their layout
* Templates can be browsed when creating new dashboards or adding widgets
# Overview
Source: https://docs.quivly.ai/dashboards/introduction
Build custom dashboards to visualize customer data
## What are Dashboards?
Dashboards let you create custom views of your customer data using configurable widgets. Combine charts, metrics, tables, and text to monitor what matters most to your business.
***
## Dashboard List
Click **Dashboards** in the main navigation to view all dashboards. The list page supports:
* **Search** by dashboard name and description
* **Filter views** - All, Favorites (starred), or Recently viewed
* **Grid or List** display mode
* **Star** dashboards to mark them as favorites
From the list, you can open, share, configure, embed, or delete any dashboard.
***
## Widget Types
Dashboards are built from widgets. Eight types are available:
| Type | Description |
| -------------- | --------------------------------------------------------------------------- |
| **Number** | Single aggregate metric (count, sum, average, etc.) with optional sparkline |
| **Bar Chart** | Compare values across categories, vertical or horizontal |
| **Line Chart** | Show trends over time with configurable curve styles |
| **Pie Chart** | Show proportions of a whole, with donut option |
| **Gauge** | Progress toward a goal |
| **Area Chart** | Filled line chart for volume visualization |
| **Table** | Tabular data view with sortable columns and pagination |
| **Text** | Rich text content with markdown formatting |
Each widget is configured with a data source (entity type, measure, dimension), display options, and optional filters.
***
## Dashboard Filters
### Dashboard-Level Filters
Global filters apply to all widgets on the dashboard. Filter conditions support AND/OR logic with operators that vary by field type (string, numeric, date).
Date filters include presets (last 7/30/90 days, this quarter, this year, custom range) and relative options (last N days/weeks/months).
### Widget-Level Filters
Individual widgets can have their own filters, independent of the dashboard filters. Enable the **Exclude Filters** toggle on a widget to prevent dashboard-level filters from affecting it.
***
## Sharing and Embedding
Dashboards can be shared via link or embedded in external sites:
* **Share link** - Generate a public link for read-only access
* **Embed code** - Get an iframe snippet to embed in websites or documentation
* **Options** - Set expiration dates, allow/disallow filters on the shared view
***
## Templates
Create dashboards from pre-built templates or save your own:
* **Library templates** - Pre-built dashboards organized by category (Overview, Executive, Customer Success, Revenue, Sales, Product, Support)
* **Saved templates** - Reusable templates created from your own dashboards
* **Browse and search** templates when creating a new dashboard
# Core Objects
Source: https://docs.quivly.ai/data-models/core-objects
Standard objects included in Quivly
## Overview
Core objects are pre-built objects that come with Quivly. They cannot be deleted or renamed, but you can add custom fields to them.
All core objects share a set of standard system fields (`id`, `external_id`, `organization_id`, `is_active`, `metadata`, `created_at`, `updated_at`) which are omitted from the tables below for brevity.
***
## Customers
The central object representing your customer accounts. All other objects reference back to a customer.
**Data sources:** CRM (Salesforce Accounts, HubSpot Companies), enriched by billing, support, and enrichment data
| Field | Type | Description |
| ------------------ | ---- | ----------------------------------------- |
| `customer_name` | text | Name of the company |
| `customer_domain` | text | Website domain |
| `customer_id` | text | Customer identifier from external systems |
| `long_description` | text | Description of the company |
| `logo_url` | text | URL to company logo |
| Field | Type | Description |
| -------------- | ---- | -------------------------------- |
| `industry` | text | Industry classification |
| `country` | text | Country where company is located |
| `country_code` | text | ISO country code |
| `city` | text | City location |
| `linkedin_id` | text | LinkedIn company ID |
| `linkedin_url` | text | URL to LinkedIn company page |
| Field | Type | Description |
| ------------------------- | ------ | ------------------------------------ |
| `employee_count` | number | Number of employees |
| `employee_count_range` | text | Employee count range (e.g., "11-50") |
| `founded_year` | number | Year company was founded |
| `annual_revenue_usd` | number | Annual revenue in USD |
| `total_funding_usd` | number | Total funding received in USD |
| `last_funding_round_date` | date | Date of last funding round |
| `funding_stage` | text | Current funding stage |
| Field | Type | Description |
| -------------------- | --------- | ---------------------------------- |
| `lifecycle_stage` | select | Customer lifecycle stage |
| `segment` | select | Customer segment |
| `tier` | select | Service tier |
| `csm_owner_id` | reference | Customer Success Manager |
| `ae_owner_id` | reference | Account Executive |
| `customer_since` | date | When customer relationship started |
| `primary_source` | text | Primary data source |
| `parent_external_id` | text | External ID of parent company |
**Allowed values:**
* **Lifecycle Stage:** `prospect`, `onboarding`, `active`, `renewing`, `at_risk`, `churned`
* **Segment:** `startup`, `smb`, `mid_market`, `enterprise`, `strategic`
* **Tier:** `strategic`, `high_touch`, `mid_touch`, `low_touch`, `self_serve`
* **Primary Source:** `salesforce`, `hubspot`, `chargebee`, `stripe`, `manual`
***
## Contacts
Individual people within customer organizations.
**Data sources:** CRM (Salesforce Contacts, HubSpot Contacts)
| Field | Type | Description |
| -------------- | ---- | ---------------------------- |
| `email` | text | Primary email address |
| `first_name` | text | Given name |
| `last_name` | text | Family name |
| `full_name` | text | Complete name (first + last) |
| `phone` | text | Primary phone number |
| `photo_url` | text | URL to profile photo |
| `linkedin_url` | text | LinkedIn profile URL |
| Field | Type | Description |
| --------------- | ---- | ----------------------------------------- |
| `title` | text | Job title |
| `department` | text | Department or team name |
| `source_system` | text | Source system (salesforce, hubspot, etc.) |
| Field | Type | Description |
| ------------------- | --------- | ---------------------------------------------- |
| `customer_id` | reference | Customer account this contact belongs to |
| `role_type` | text | CS role type |
| `last_activity_at` | date | Timestamp of last recorded activity |
| `last_contacted_at` | date | Timestamp when contact was last reached out to |
**Allowed values:**
* **Role Type:** `champion`, `decision_maker`, `economic_buyer`, `influencer`, `end_user`, `detractor`
***
## Opportunities
Sales opportunities including new deals, renewals, and expansions.
**Data sources:** CRM (Salesforce Opportunities, HubSpot Deals)
| Field | Type | Description |
| ------------------ | ---- | --------------------------------- |
| `name` | text | Name or title of the opportunity |
| `description` | text | Detailed description |
| `opportunity_type` | text | Classification of the opportunity |
| `stage` | text | Stage in sales/CS process |
| `status` | text | Current status |
**Allowed values:**
* **Opportunity Type:** `new`, `expansion`, `renewal`, `retention`
* **Stage:** `qualification`, `proposal`, `negotiation`, `closed_won`, `closed_lost`
* **Status:** `open`, `won`, `lost`, `abandoned`
| Field | Type | Description |
| ------------------ | ------ | --------------------------------------- |
| `amount` | number | Monetary value of the opportunity |
| `currency` | text | ISO 4217 currency code (e.g., USD, EUR) |
| `close_date` | date | Expected or actual close date |
| `last_activity_at` | date | Timestamp of last recorded activity |
| `source_system` | text | Source system (salesforce, hubspot) |
| Field | Type | Description |
| -------------------- | --------- | -------------------------------------------- |
| `customer_id` | reference | Customer account this opportunity belongs to |
| `primary_contact_id` | reference | Main contact person |
| `owner_id` | reference | Assigned owner |
***
## Subscriptions
Recurring billing subscriptions from your payment platform.
**Data sources:** Stripe Subscriptions
| Field | Type | Description |
| ------------------- | ---- | ------------------------------------------------------------------ |
| `description` | text | Description or memo |
| `status` | text | Subscription status |
| `currency` | text | ISO 4217 currency code |
| `collection_method` | text | How payment is collected |
| `items` | json | Array of subscription items with price, quantity, and product info |
**Allowed values:**
* **Status:** `active`, `past_due`, `canceled`, `unpaid`, `trialing`, `incomplete`, `incomplete_expired`, `paused`
* **Collection Method:** `charge_automatically`, `send_invoice`
| Field | Type | Description |
| ---------------------- | ------ | ------------------------------------------------- |
| `start_date` | date | When the subscription originally started |
| `current_period_start` | date | When the current billing period started |
| `current_period_end` | date | When the current billing period ends |
| `billing_cycle_anchor` | date | Day of month when billing cycle resets |
| `trial_start` | date | When the trial period started |
| `trial_end` | date | When the trial period ends |
| `days_until_due` | number | Days after invoice creation before payment is due |
| Field | Type | Description |
| ---------------------- | ------- | ------------------------------------------------------ |
| `cancel_at_period_end` | boolean | If true, subscription cancels at end of current period |
| `cancel_at` | date | When the subscription is scheduled to cancel |
| `canceled_at` | date | When subscription was marked for cancellation |
| `ended_at` | date | When subscription actually ended |
| `cancellation_details` | json | Reason, feedback, and comments about cancellation |
| Field | Type | Description |
| --------------- | --------- | --------------------------------------------- |
| `customer_id` | reference | Customer account this subscription belongs to |
| `source_system` | text | Billing provider source |
***
## Invoices
Billing transactions and payment history.
**Data sources:** Stripe Invoices
| Field | Type | Description |
| ------------------- | ---- | ----------------------------- |
| `number` | text | Human-readable invoice number |
| `status` | text | Invoice status |
| `billing_reason` | text | Why this invoice was created |
| `collection_method` | text | How payment is collected |
| `currency` | text | ISO 4217 currency code |
**Allowed values:**
* **Status:** `draft`, `open`, `paid`, `uncollectible`, `void`
* **Billing Reason:** `subscription_create`, `subscription_cycle`, `subscription_update`, `manual`
* **Collection Method:** `charge_automatically`, `send_invoice`
| Field | Type | Description |
| ------------------------ | ------ | -------------------------- |
| `subtotal` | number | Total before tax |
| `subtotal_excluding_tax` | number | Subtotal without tax |
| `tax` | number | Total tax |
| `total` | number | Total amount including tax |
| `total_excluding_tax` | number | Total without tax |
| `amount_due` | number | Amount currently owed |
| `amount_paid` | number | Amount that has been paid |
| `amount_remaining` | number | Amount still to be paid |
| Field | Type | Description |
| -------------------- | ------ | ------------------------------------------------------------- |
| `due_date` | date | When payment is due |
| `period_start` | date | Start of billing period covered |
| `period_end` | date | End of billing period covered |
| `source_created_at` | date | Original creation date from billing provider |
| `status_transitions` | json | Timestamps for status changes (finalized, paid, voided, etc.) |
| `attempt_count` | number | How many times payment has been attempted |
| Field | Type | Description |
| -------------------- | ---- | ------------------------------------------------------ |
| `line_items` | json | Array of line items with description, amount, quantity |
| `hosted_invoice_url` | text | Link to view invoice online |
| `invoice_pdf` | text | Link to download invoice as PDF |
| Field | Type | Description |
| ----------------- | --------- | ---------------------------------------- |
| `customer_id` | reference | Customer account this invoice belongs to |
| `subscription_id` | reference | Subscription this invoice is for |
| `source_system` | text | Billing provider source |
***
## Support Tickets
Customer support requests and issues.
**Data sources:** Pylon Issues
| Field | Type | Description |
| --------------- | ---- | ----------------------------------- |
| `ticket_number` | text | Human-readable number (e.g., #1234) |
| `subject` | text | Subject line |
| `description` | text | Ticket body |
| `status` | text | Ticket status |
| `priority` | text | Ticket priority |
| `ticket_type` | text | Ticket type |
| `channel` | text | Source channel |
| `ticket_url` | text | Link to source system |
| `tags` | json | Array of tag strings |
**Allowed values:**
* **Status:** `open`, `pending`, `solved`, `closed`
* **Priority:** `low`, `normal`, `high`, `urgent`
* **Type:** `question`, `incident`, `problem`, `task`
* **Channel:** `email`, `chat`, `phone`, `web`, `slack`
| Field | Type | Description |
| ----------------- | ---- | ---------------------------------------------- |
| `requester_email` | text | Email of requester (used to match to contacts) |
| `requester_name` | text | Display name of requester |
| `group_name` | text | Team/group handling the ticket |
| Field | Type | Description |
| ------------------------------ | ------ | ------------------------------------------- |
| `first_response_time_seconds` | number | Time from creation to first reply (seconds) |
| `full_resolution_time_seconds` | number | Time from creation to resolution (seconds) |
| `reply_count` | number | Number of agent replies |
| `satisfaction_score` | number | Normalized CSAT score (0-100 scale) |
| `first_response_at` | date | When first response was sent |
| `resolved_at` | date | When ticket was resolved |
| Field | Type | Description |
| -------------------- | --------- | ------------------------------------------------------------ |
| `customer_id` | reference | Resolved from account or requester |
| `primary_contact_id` | reference | Contact who raised ticket |
| `assignee_user_id` | reference | Assigned agent |
| `source_system` | text | Support provider (pylon, zendesk, intercom, freshdesk, etc.) |
***
## Call Recordings
Customer call transcripts and summaries.
**Data sources:** Fireflies, Fathom
| Field | Type | Description |
| ------------------ | ------ | ---------------------------- |
| `title` | text | Title of the call or meeting |
| `call_time` | date | When the call happened |
| `duration_seconds` | number | Total duration in seconds |
| `meeting_url` | text | Zoom/Teams/Meet link |
| `calendar_id` | text | ID of the calendar event |
| Field | Type | Description |
| ----------------- | ---- | ------------------------------------------------------------------------------------- |
| `recording_url` | text | Dashboard or viewer URL |
| `audio_url` | text | Direct link to audio file |
| `video_url` | text | Direct link to video file |
| `transcript_text` | text | Plain text transcript for search and AI analysis |
| `summary` | json | AI-generated meeting summary (action items, keywords, overview, topics, meeting type) |
| `source_insights` | json | Sentiments, categories, and speaker statistics from provider |
| Field | Type | Description |
| -------------------- | --------- | ------------------------------------------------ |
| `participants` | json | Array of participant objects with email and name |
| `customer_id` | reference | Customer resolved from participant emails |
| `primary_contact_id` | reference | Contact with most talk time or organizer |
| `organizer_id` | reference | Team member who organized the call |
| `source_system` | text | Source system (fireflies, fathom, gong) |
***
## Market Signals
External intelligence about customer companies.
**Data sources:** Quivly data enrichment
| Field | Type | Description |
| ------------------- | ---- | --------------------------------------- |
| `insight_title` | text | Title of the signal |
| `insight_summary` | text | Summary of the signal |
| `insight_type` | text | Type of signal |
| `insight_data` | json | Core signal data |
| `insight_timestamp` | date | When the signal was recorded |
| `source` | text | Source of the signal |
| `sentiment` | text | Sentiment (positive, negative, neutral) |
| `relevance_level` | text | Level of relevance (high, medium, low) |
| `relevance_reason` | text | Why the signal is relevant |
| `tags` | json | Tags associated with the signal |
| `customer_id` | text | Customer this signal relates to |
**Signal types:** Funding rounds, Hiring, Layoffs, Acquisitions, Leadership changes
***
## Product Usage
Customer usage metrics from your data warehouse.
**Data sources:** BigQuery, Snowflake, ClickHouse
| Field | Type | Description |
| ----------------- | --------- | ------------------------------------------------------------------------------ |
| `customer_id` | reference | Customer account |
| `product_id` | reference | Billing product (optional - for product-specific usage) |
| `usage_timestamp` | date | When the usage was measured |
| `granularity` | text | Time period: `hourly`, `daily`, `weekly`, `monthly` |
| `metric_key` | text | Metric identifier (e.g., `gb_scanned`, `credits`, `api_calls`, `active_users`) |
| `value` | number | Raw usage value |
| `billed_value` | number | Usage value normalized for billing purposes |
| `source` | text | Origin of data (`clickhouse`, `warehouse`, `metronome_export`, etc.) |
| `properties` | json | Additional metric metadata |
# Custom Fields
Source: https://docs.quivly.ai/data-models/custom-fields
Add fields to objects to capture additional data
## Overview
Custom fields let you add properties to any object (core or custom) to capture business-specific data.
***
## Field Types
| Type | Use for |
| ---------------- | ------------------------------- |
| **String** | Short text (names, IDs) |
| **Text** | Long text (notes, descriptions) |
| **Number** | Numeric values |
| **Currency** | Monetary amounts |
| **Percentage** | Percentage values |
| **Boolean** | Yes/No flags |
| **Date** | Dates |
| **Timestamp** | Date and time |
| **Email** | Email addresses |
| **Phone** | Phone numbers |
| **URL** | Web links |
| **Select** | Single choice from a list |
| **Multi-Select** | Multiple choices from a list |
| **JSON** | Structured data |
| **Object** | Reference to another object |
***
## Adding a Custom Field
Go to **Settings** → **Objects** → Select the object
In the **Attributes** tab, click **Add Field**
Fill in the field details:
* **Label** - Display name
* **Type** - Select from available types
* **Description** - Help text for users
* **Category** - Group related fields
Configure additional options:
* **Required** - Must have a value
* **Filterable** - Can filter by this field
* **Read-only** - Cannot be edited after creation
For Select/Multi-Select fields, define the allowed values.
***
## AI-Powered Fields
When adding a customer field, the modal offers **Standard** or **AI-powered**. AI-powered fields are computed by AI from each customer's data on a schedule — see [AI fields](/product/ai-fields).
***
## Editing Fields
Click any field to edit its properties. You can change:
* Label and description
* Category
* Required/filterable/read-only settings
* Allowed values (for select fields)
Field type and API name cannot be changed after creation.
***
## Archiving Fields
To archive a field you no longer need:
1. Click the field
2. Select **Archive**
3. Provide a reason
Archived fields are hidden but data is retained.
# Custom Objects
Source: https://docs.quivly.ai/data-models/custom-objects
Create objects for your business-specific data
## Overview
Custom objects let you track data that doesn't fit into Quivly's core objects. Common examples include implementation projects, success plans, or training sessions.
***
## Creating a Custom Object
Navigate to **Settings** → **Objects**
Click **Add Custom Object** and fill in:
* **Name** - Display name (e.g., "Implementation Project")
* **Description** - What this object represents
* **Icon** - Visual identifier
After creating the object, add fields to capture your data. See [Custom Fields](/data-models/custom-fields) for field types.
***
## Editing Custom Objects
Click on any custom object to edit:
* Name and description
* Icon
* Field definitions
The object's API name (entity type) cannot be changed after creation.
***
## Archiving Custom Objects
To archive a custom object you no longer need:
1. Open the object settings
2. Click **Archive**
3. Provide a reason
Archived objects are hidden but data is retained.
# Overview
Source: https://docs.quivly.ai/data-models/introduction
How Quivly organizes your customer data
## Overview
Objects are structured containers that hold different types of data in Quivly. When you connect integrations (Salesforce, HubSpot, Stripe, etc.), data is mapped to objects to create a unified customer view.
***
## Object Types
| Type | Description |
| ------------------ | ----------------------------------------------------------------------------------- |
| **Core Objects** | Pre-built objects (Customers, Contacts, Opportunities, etc.) that cannot be deleted |
| **Custom Objects** | Objects you create to track business-specific data |
***
## Core Objects
Quivly includes these core objects:
* **Customers** - Your customer accounts/companies
* **Contacts** - People within customer organizations
* **Opportunities** - Deals, renewals, expansions from your CRM
* **Subscriptions** - Recurring revenue from billing systems
* **Invoices** - Billing transactions and payments
* **Contracts** - MSAs, order forms, and renewals from your CRM
* **Support Tickets** - Customer support requests
* **Call Recordings** - Meeting transcripts from call recording tools
* **Market Signals** - External company intelligence (funding, hiring, etc.)
* **Product Usage** - Customer activity metrics from your data warehouse or the Push API
* **External Users** - People from your connected systems (CRM owners, support agents) used for ownership references
***
## Object Relationships
All objects relate to Customers:
```
Customer
├── Contacts
├── Opportunities
├── Contracts
├── Subscriptions
├── Invoices
├── Support Tickets
├── Call Recordings
└── Product Usage
```
***
## Managing Objects
Navigate to **Settings** → **Objects** to:
* View all core and custom objects
* See field definitions for each object
* Add custom fields to any object
* Configure integration field mappings
# API Keys
Source: https://docs.quivly.ai/developers/api-keys
Create and manage organization API keys under Settings → Developer. Keys authenticate the Usage Push API.
API keys authenticate programmatic access to Quivly — primarily the [Usage Push API](/integrations/product-usage/api-overview). Manage them under **Settings → Developer**.
## Creating a key
1. Go to **Settings → Developer**.
2. Click create, name the key (e.g. `production-backend`), and generate it.
3. **Copy the key immediately** — treat it like a password and store it in your secrets manager.
Use it as a bearer token:
```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://app.quivly.ai/api/v1/usage/events \
-X POST -H "Content-Type: application/json" \
-d '{"events":[{"external_customer_id":"cus_acme","metric_key":"api_calls","value":1500}]}'
```
Keys are organization-scoped — one key works for your whole org, with no per-key permission levels.
## Archiving a key
Archive from the same page; you'll confirm by typing the key's name. Archiving is permanent and immediately breaks any integration still using the key, so rotate consumers first.
## FAQ
No — the [MCP server](/developers/mcp-server) uses per-user OAuth sign-in, not API keys.
Create a new key, switch your integrations to it, then archive the old one.
# Developers FAQ
Source: https://docs.quivly.ai/developers/faq
Common questions about the Quivly MCP server, API keys, the Usage Push API, and importing skills from GitHub.
Add `https://mcp.quivly.ai/connect` as a custom connector in Claude (Settings → Connectors), or run `claude mcp add --transport http quivly https://mcp.quivly.ai/connect` in Claude Code. First use opens a one-time Quivly sign-in. See [MCP server](/developers/mcp-server).
Yes, with one exception: `create_notebook` can generate a new AI notebook. Nothing can be edited or deleted through MCP, and every call is logged. Access is scoped to the signed-in user's organization. See [security and compliance](/security).
OAuth 2.1 — each user signs in with their own Quivly account in the browser on first connect. No API keys or shared tokens, and answers are scoped to the user's organization.
POST batches of events (up to 1,000) to `https://app.quivly.ai/api/v1/usage/events` with an org API key as a bearer token. Events carry `external_customer_id`, `metric_key`, `value`, and optionally a timestamp, granularity, and properties. See the [Push API](/integrations/product-usage/api-overview).
Events are stored only after the Push API source is published. Before that, calls run in verify mode — resolved and reported, never stored. Also check the response's errors array for unmatched customer IDs. Use `?dry_run=true` to test safely anytime.
Send an `Idempotency-Key` header (a UUID) — retries with the same key replay the original response instead of double-writing.
Yes — author them as `SKILL.md` files in the Anthropic Agent Skills format and import via the GitHub App. Re-import to sync changes. See [GitHub skill import](/developers/github-skill-import).
The documented public API today is the Usage Push API (data in). For reading data programmatically, the MCP server is the supported surface.
# Import Skills from GitHub
Source: https://docs.quivly.ai/developers/github-skill-import
Install the Quivly GitHub App, pick a repo, and import SKILL.md files as draft skills. Re-import to sync changes.
Keep your [skills](/product/skills) in a Git repo — reviewed in PRs, versioned, shared — and import them into Quivly with the native GitHub App.
## One-time setup
Connect GitHub under **Settings → Integrations → GitHub**: click **Connect with GitHub** and install the Quivly GitHub App on the repos you want. The app only asks for read access to repository contents. The connection is org-wide — one install serves your whole Quivly organization. Public repos work without an install.
## Importing
From **Settings → AI → Skills → Create → Import from GitHub**:
Browse or search the repos your installation can see.
Quivly scans for `SKILL.md` files (the [Agent Skills format](/developers/skill-format)) and previews what it found — nothing is written yet.
Optionally let AI suggest which Quivly data tools each skill should use — the spec's `allowed-tools` don't carry over.
Skills land as drafts. Review and publish them like any other skill.
## Keeping skills in sync
There's no webhook auto-sync — re-importing is the sync:
* **Re-import the repo** — unchanged files are skipped, changed files update the skill's content (never its tools), new files create new drafts.
* **Refetch one skill** — from the skill's page, pull its latest content from GitHub in place.
Skills track their source repo and path, so updates land on the right skill. Failures are per-file: one bad skill doesn't block the rest.
## Limits
* Works comfortably up to \~100 skills per repo.
* Files over 1 MB import with empty instructions.
* `scripts/`, `references/`, and `assets/` folders aren't ingested (skills that have them are flagged).
## FAQ
No personal tokens are stored. Access uses the GitHub App's short-lived installation tokens.
The skill stays in Quivly. A refetch reports the source as missing and lets you relink it.
No — updates only touch name, description, and instructions. Tool attachments are never changed by a sync.
# Quivly MCP Server
Source: https://docs.quivly.ai/developers/mcp-server
Connect Claude, ChatGPT, Cursor, and other AI tools to your Quivly customer data with one URL: https://mcp.quivly.ai. OAuth sign-in, read-only, org-scoped.
Quivly ships a hosted [MCP](https://modelcontextprotocol.io) server, so any MCP-capable AI tool — Claude, ChatGPT, Cursor, VS Code, and others — can query your customer data directly. Ask Claude "which of my accounts are most at risk right now?" and it answers from your live Quivly data.
**Server URL:**
```text theme={null}
https://mcp.quivly.ai
```
The first connection opens your browser once to sign in to Quivly (OAuth). Answers are read-only and scoped to your organization — you only ever see your own org's data. See [security and compliance](/security).
In-app setup guides for each client live at **Settings → AI → MCP**.
## Client setup
**Settings → Connectors → Add custom connector**, paste the URL, click Add, and complete the one-time sign-in. On Team/Enterprise plans, an Owner adds it under Organization settings → Connectors.
```bash theme={null}
claude mcp add --transport http quivly https://mcp.quivly.ai/connect
```
Then run `/mcp` to sign in. Add `--scope user` to use it across all projects.
Add to `mcp.json`:
```json theme={null}
{ "mcpServers": { "quivly": { "url": "https://mcp.quivly.ai/connect" } } }
```
Add to `.vscode/mcp.json`:
```json theme={null}
{ "servers": { "quivly": { "type": "http", "url": "https://mcp.quivly.ai/connect" } } }
```
Enable Developer mode, then **Settings → Connectors → Create**, name it Quivly, and paste the URL.
Add Quivly as a remote (Streamable HTTP) MCP server with the URL above and complete the OAuth sign-in. Windsurf, Zed, and Cline configs are in the in-app setup guides.
## What it can do
Around 40 tools cover customer profiles, health scores, revenue, usage, contracts, calls and transcripts, support tickets, opportunities, conversations, notes, notebooks, projects, cross-customer aggregation, plus live Slack, Salesforce, and HubSpot lookups. One tool writes: `create_notebook` generates an [AI notebook](/product/notebooks) using one of your [skills](/product/skills). Everything else is read-only.
See the full [tool reference](/developers/mcp-tools).
## Usage analytics
**Settings → AI → MCP → Usage** shows who's connecting and what they ask: users, sessions, breakdowns by client app and by integration, filters, and an "Ask your usage" chat for querying it in natural language. Per-user breakdowns are admin-only.
## FAQ
Access requires each user's own Quivly sign-in, answers are scoped to their organization, everything except notebook creation is read-only, and every tool call is logged in the usage analytics.
Yes — the OAuth sign-in is per user, so access and audit trails follow the individual.
No. The only write operation is creating a new notebook. Nothing can be edited or deleted through MCP.
# MCP Tool Reference
Source: https://docs.quivly.ai/developers/mcp-tools
Every tool the Quivly MCP server exposes, grouped by category — customer context, health, revenue, search, calls, notebooks, aggregation, and live Slack/Salesforce/HubSpot.
All tools available once you [connect to the Quivly MCP server](/developers/mcp-server). All are read-only except `create_notebook`.
## Start here
| Tool | What it returns |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `get_account_context` | A full 360° briefing on one customer: profile, MRR, health score and trend, open pipeline, usage, market signals, top calls, recent tickets, notebooks, firmographics, custom fields |
| `search_customers` | Find customers by name or domain — name, domain, segment, MRR, health risk |
| `list_contacts` | Contacts for one customer — name, title, email, role |
## Health
| Tool | What it returns |
| ----------------------- | ------------------------------------------------------------------------------------------ |
| `get_health_score` | Latest health score, risk level, and contributing factors |
| `analyze_health_trends` | Health score time series with trend direction |
| `search_insights` | Market signals and competitive intel for a customer, filterable by relevance and sentiment |
## Revenue & usage
| Tool | What it returns |
| -------------------------- | ---------------------------------------------------------------------- |
| `get_revenue` | Subscriptions, recent invoices, MRR, total paid, outstanding balance |
| `list_usage` | Product usage time series by metric, granularity, and lookback |
| `list_contracts` | Contracts synced from the CRM (MSAs, order forms, renewals) |
| `get_billing_customer` | Live billing record from the connected billing provider |
| `get_billing_subscription` | Live subscription detail — line items, trial status, next invoice date |
## Cross-customer search
| Tool | What it returns |
| ---------------------- | ---------------------------------------------------------------------------------- |
| `search_calls` | Call recordings by title, customer, or date range |
| `search_opportunities` | Pipeline deals by customer, stage, amount, close date |
| `search_tickets` | Support tickets by customer, status, priority, or text |
| `search_conversations` | AI-enriched Slack and email threads — summary, sentiment, action items, key quotes |
## Calls
| Tool | What it returns |
| --------------------- | ------------------------------------------------------------------- |
| `get_call_summary` | AI summary of one call — overview, key points, action items, topics |
| `get_call_transcript` | Full raw transcript (up to 50,000 characters) |
## Notes, notebooks & skills
| Tool | What it returns |
| --------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `list_notes` | Team-written notes on a customer, call, or notebook |
| `search_notebooks` | Find notebooks by content |
| `get_notebook` | One notebook's full content as text |
| `list_skills` / `get_skill` | Your org's skills and their instructions |
| `create_notebook` | **(write)** Start generating an AI notebook for a customer using a skill; returns a request ID immediately |
| `get_notebook_status` | Poll a generation: running, ready (with link), or failed |
## Projects & reference data
| Tool | What it returns |
| --------------------- | ---------------------------------------------------------- |
| `list_projects` | Projects, optionally by customer or status |
| `list_products` | Your product catalog |
| `list_external_users` | People from connected systems — CSM owners, support agents |
## Aggregation & comparison
| Tool | What it returns |
| ------------------------------ | ------------------------------------------------------------------------------ |
| `compare_customers` | 2–5 customers side by side — MRR, health, usage, tickets, opportunities |
| `aggregate_metrics` | Count, sum, average, min, max of a metric across customers, optionally grouped |
| `list_top_customers_by_metric` | Top or bottom N customers by a metric |
## Live connected apps
Available when the corresponding integration is connected:
| Tool | What it does |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `search_slack_messages` | Search Slack workspace messages |
| `get_slack_channel_history` | Recent messages from a channel |
| `slack_list_channels` / `slack_list_users` | Channels and workspace members |
| `get_slack_thread_replies` | Replies in a thread |
| `get_salesforce_record` / `search_salesforce_records` / `list_salesforce_records` | Live Salesforce record lookup, read-only SOQL search, and recent-record listing |
| `get_hubspot_record` / `search_hubspot_records` / `list_hubspot_records` | Live HubSpot record lookup, search, and recent-record listing |
Salesforce and HubSpot queries return up to 50 rows per call.
# Skill Format (SKILL.md)
Source: https://docs.quivly.ai/developers/skill-format
Quivly imports skills in the Anthropic Agent Skills format — a SKILL.md file with YAML frontmatter and markdown instructions.
Quivly skills can be authored as code, in the [Anthropic Agent Skills](https://agentskills.io/specification) format, and [imported from GitHub](/developers/github-skill-import). A skill is a folder containing a `SKILL.md` file.
## The file
```markdown theme={null}
---
name: renewal-risk-read
description: Assess renewal risk for a customer from health, usage, and conversations.
---
You are preparing a renewal risk assessment...
## What to produce
1. A risk rating with reasoning
2. Evidence from calls and tickets
3. Recommended next steps
```
## How fields map into Quivly
| SKILL.md | Quivly | Notes |
| -------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------- |
| `name` | Slash command + display name | Required. Lowercase-with-hyphens; falls back to the folder name. Max 64 chars |
| `description` | Description | Required. Max 1,024 chars |
| Markdown body | Instructions | Max 50,000 chars |
| `license`, `compatibility`, `metadata` | Preserved as source metadata | Optional spec fields |
| `allowed-tools` | **Not imported** | Anthropic tool names don't map to Quivly's catalog — the import flow suggests Quivly tools instead |
Imported skills always land as **drafts** with no tools attached (or the tools you accepted from the AI suggestion step). Review, attach tools, and publish in **Settings → AI → Skills**.
## What isn't ingested
Only `SKILL.md` content is imported. Supporting folders from the spec (`scripts/`, `references/`, `assets/`) are not ingested; skills that have them are flagged so you know part of the skill lives outside Quivly. Files over 1 MB import with empty instructions.
## FAQ
Yes — any repo following the Agent Skills spec imports, including public community repos. You'll attach Quivly data tools during import since Claude tool names don't carry over.
No — most teams create skills in the app. The format matters when you want skills version-controlled in a repo or shared across tools.
# Frequently Asked Questions
Source: https://docs.quivly.ai/faq
Common questions about what Quivly is, what it connects to, how its AI works, and how data is handled.
## About Quivly
Quivly is an AI-native customer intelligence platform for revenue and customer success teams. It unifies CRM, billing, support, call, Slack, and product usage data into one customer view, then layers AI on top: health scores, a research assistant (Ask Quivly), automated agents, drafted actions, AI-written notebooks, and AI-computed fields.
Customer success and revenue teams that want one place to see customer health and act on it — and revenue operations teams who set up the data. Developers get an MCP server and APIs on top of the same data.
Salesforce, HubSpot (CRM); Stripe (billing); Pylon (support); Fireflies, Fathom, Granola (calls); Slack; Snowflake, BigQuery, PostHog, and a Push API (product usage); Gmail, Google Calendar, Calendly (agent tools); GitHub (skill import); plus any third-party MCP server. See [integrations](/integrations/introduction).
Yes — a hosted MCP server at `https://mcp.quivly.ai/connect` that connects Claude, ChatGPT, Cursor, and other AI tools to your Quivly data with per-user OAuth sign-in. See [MCP server](/developers/mcp-server).
## AI
No. Data integrations are read-only. Outbound activity — a Slack message, an email, a calendar invite — only happens through agent steps and actions that your team configures, and you can require human review before anything sends. See [security and compliance](/security).
Agents only act when you build and publish them, and any step can sit behind a Review gate that pauses for human approval. Recommendations from signal rules are always drafts — a person reviews and sends them.
Each customer is scored across up to five weighted categories — revenue, product usage, engagement, support, and market signals — using thresholds you configure, with AI-generated risk and growth signals. See [health scores](/health-scores/introduction).
## Data
Yes — all data is scoped to your organization, and every surface (app, Slack bot, MCP server) only answers from your own org's data. See [security and compliance](/security).
Records from different systems are linked by identifiers like email domains and external IDs into one customer profile. See [cross-system linking](/field-mappings/cross-system-linking).
## Getting started
Connect your CRM, then billing, then whatever else you have — each source makes scores and answers richer. The [quick start guide](/quickstart-admin) walks through it.
Most teams are live in less than a week, mainly gated by initial sync volume and mapping review. Connecting an integration takes minutes and data starts flowing right away; the [quick start guide](/quickstart-admin) covers the full setup.
It's self-serve — an admin connects the integrations, reviews field mappings, and configures health scores directly in the app. The team is available for optional onboarding help whenever you want it: email [support@quivly.ai](mailto:support@quivly.ai) or [book time](https://cal.com/chandrika).
Email [support@quivly.ai](mailto:support@quivly.ai) or [book time with the team](https://cal.com/chandrika).
# Cross-System Linking
Source: https://docs.quivly.ai/field-mappings/cross-system-linking
Link customers across multiple integrations
## Overview
Cross-system linking connects the same customer across different integrations. For example, link a HubSpot company to a Salesforce account so data from both systems appears on a single customer profile.
***
## How It Works
When you have multiple integrations connected (e.g., Salesforce as primary CRM and HubSpot for marketing), you can link records between them using ID fields that exist in both systems.
**Two linking modes:**
| Mode | Use when |
| -------------------- | ------------------------------------------------------------------------------------------------ |
| **Primary has ID** | Your primary system stores the secondary system's ID (e.g., Salesforce has a "HubSpot ID" field) |
| **Secondary has ID** | Your secondary system stores the primary system's ID (e.g., HubSpot has a "Salesforce ID" field) |
***
## Configuring Cross-System Linking
Navigate to **Settings** → **Objects** → **Customers** → **Configuration** tab
Expand the **Advanced Settings** section below the field mappings (available on the Customers object)
Choose which secondary integration you want to link (lists all connected integrations except your primary)
Select how the systems are linked:
**Primary has ID:** Select the field in your primary system that contains the secondary system's ID
**Secondary has ID:** Select the field in your secondary system that contains the primary system's ID
Click **Save**. Records will be linked on the next sync.
***
## Example
**Setup:** Salesforce (primary) and HubSpot (secondary)
**Scenario:** Your HubSpot company records have a custom property called `salesforce_account_id` that stores the Salesforce Account ID.
**Configuration:**
1. Select **HubSpot** as secondary system
2. Choose **Secondary has ID**
3. Select `salesforce_account_id` from the HubSpot fields
4. Save
Now when Quivly syncs, it matches HubSpot companies to Salesforce accounts using this ID field.
***
## Status Indicators
| Status | Meaning |
| -------------- | ------------------------------------------ |
| **Linked** | Cross-system linking is configured |
| **Not linked** | No linking configured for this integration |
***
## Removing a Link
Click **Remove** next to a linked integration to disable cross-system linking.
# Overview
Source: https://docs.quivly.ai/field-mappings/introduction
Understanding how to map data from external systems to Quivly
## What are Field Mappings?
Field mappings define **how data from external systems** (like Salesforce, HubSpot, Stripe, Pylon) **maps to Quivly's data model**. When integrations sync data, field mappings tell Quivly which external fields should populate which Quivly fields.
**Think of field mappings as translation rules** between external systems and Quivly. They ensure data from different sources flows into the right places in your unified customer view.
***
## Why Field Mappings Matter
Map HubSpot Companies, Salesforce Accounts, and Stripe Customers all to Quivly's Customer object
Map custom CRM properties or billing metadata to Quivly fields
Control which fields sync and how they're formatted
Use mapped fields (like domain, email) to match customers across integrations
***
## How Field Mappings Work
You authenticate with an external system (e.g., HubSpot) and grant Quivly access to read data.
Quivly discovers what object types are available in that system (e.g., HubSpot has Companies, Contacts, Deals, Tickets).
For each external object type, you define:
* Which Quivly object it maps to
* Which external fields map to which Quivly fields
On each sync cycle, Quivly pulls data from the external system and populates Quivly fields based on your mappings.
Mapped data appears in customer profiles, lists, and dashboards - unified across all your integrations.
***
## Default Mappings vs. Custom Mappings
### Default Mappings
When you first connect an integration, Quivly provides **default mappings** for common fields:
**HubSpot Example:**
* HubSpot Companies → Quivly Customers
* `name` → `customer_name`
* `domain` → `customer_domain`
* `num_employees` → `employee_count`
* `industry` → `industry`
* `hubspot_owner_id` → `csm_owner_id`
**Stripe Example:**
* Stripe Customers → Quivly Customers
* `name` → `name`
* `email` → `email`
* `description` → `description`
Default mappings get you started immediately. Standard fields sync automatically with best practices baked in.
### When to Customize Mappings
Your Salesforce or HubSpot has custom properties (e.g., "Customer Tier", "Implementation Status") that you want in Quivly.
**Solution:** Map those custom external fields to Quivly custom fields. You can create new custom fields inline during mapping.
External field names differ from Quivly's expected names.
**Example:** Salesforce uses `AnnualRevenue`, but Quivly expects `annual_revenue_usd`.
**Solution:** Map `AnnualRevenue` → `annual_revenue_usd` in the field mapping editor.
Some external fields are irrelevant or sensitive and shouldn't sync.
**Example:** Don't sync HubSpot's internal tracking properties.
**Solution:** Leave those fields unmapped so they don't sync.
***
## Object-Level Mapping
Before mapping fields, you map **object types** from external systems to Quivly objects:
| External Object | Quivly Object |
| --------------- | ---------------- |
| Accounts | Customers |
| Contacts | Contacts |
| Users | External Users |
| Opportunities | Opportunities |
| Products | Billing Products |
| External Object | Quivly Object |
| --------------- | -------------- |
| Companies | Customers |
| Contacts | Contacts |
| Owners | External Users |
| Deals | Opportunities |
| External Object | Quivly Object |
| --------------- | ---------------- |
| Customers | Customers |
| Products | Billing Products |
| Subscriptions | Subscriptions |
| Invoices | Invoices |
| External Object | Quivly Object |
| --------------- | --------------- |
| Issues | Support Tickets |
| Source | External Object | Quivly Object |
| --------- | --------------- | --------------- |
| Fireflies | Transcripts | Call Recordings |
| Fathom | Meetings | Call Recordings |
BigQuery, Snowflake, Redshift, ClickHouse, PostgreSQL, and MySQL integrations map warehouse tables to the **Product Usage** object via usage mapping configurations rather than direct object mappings.
**One external object can only map to one Quivly object**, but multiple external object types can map to the same Quivly object (e.g., HubSpot Companies and Salesforce Accounts both map to Customers).
***
## Field-Level Mapping
Once object types are mapped, you map individual fields. Each mapping connects an **external field** to a **Quivly field**.
### Example: HubSpot Companies → Quivly Customers
| External Field (HubSpot) | Quivly Field | Notes |
| ------------------------ | ------------------------ | ------------------------------ |
| `name` | `customer_name` | Company name |
| `domain` | `domain` | Used for cross-system matching |
| `industry` | `industry` | Direct mapping |
| `numberofemployees` | `employee_count` | Number field |
| `annualrevenue` | `annual_revenue_usd` | Currency field |
| `hubspot_owner_id` | `csm_owner_id` | Reference to User object |
| `customer_tier` (custom) | `customer_tier` (custom) | Custom field mapping |
Some fields are **auto-computed** by Quivly during sync (e.g., deriving a customer domain from an email address, or calculating opportunity status from CRM boolean fields). These appear as read-only in the mapping editor.
Core field mappings may be **locked** for certain integrations to prevent accidental changes. Custom field mappings can always be added or modified.
# Field Mapping Workflow
Source: https://docs.quivly.ai/field-mappings/mapping-workflow
Map fields from your integrations to Quivly objects
## Overview
Field mapping connects data from your integrated systems (Salesforce, HubSpot, Stripe, etc.) to Quivly objects. Map external fields to core Quivly fields or create custom fields during the process.
***
## Prerequisites
* Integration is connected and has synced data
* You have Admin access
***
## Configuring Field Mappings
Go to **Settings** → **Objects** → Select the object you want to configure (e.g., Customers)
In the **Configuration** tab, select which integration to map from the dropdown.
Once you save a mapping, the integration is locked and can only be changed by support.
The left panel shows all fields available from the external system. Use the search box to filter fields. Hover over fields to see sample values.
For each external field you want to sync:
1. Click the field
2. Select a Quivly field from the dropdown, or click **Create New Field** to add a custom field
3. The mapping is staged — an "Unsaved changes" badge appears until you click **Save Mappings**
When creating a new field:
* Enter a field label
* Select the field type (string, number, boolean, date, email, url, json, or reference)
* For reference fields, select which object it links to
Click **Save** to activate your mappings. Changes apply on the next sync.
***
## Field Types
| Type | Use for |
| ------------- | ----------------------------- |
| **String** | Text values |
| **Number** | Numeric values |
| **Boolean** | True/false values |
| **Date** | Dates and timestamps |
| **Email** | Email addresses |
| **URL** | Web links |
| **JSON** | Complex nested data |
| **Reference** | Links to other Quivly objects |
***
## Auto-Computed Fields
Some fields are automatically computed by Quivly and cannot be manually mapped. These appear in a separate "Auto-computed Fields" section with a lock icon.
***
## Notes
* Each external field can only be mapped to one Quivly field
* Core field mappings are locked after first save
* Use the **Raw Data Preview** section to see sample data from the external system
# Configuration
Source: https://docs.quivly.ai/health-scores/configuration
Create a health score config with the three-step wizard — choose who to score, set buckets and category weights, add AI scoring intelligence — then tune metric thresholds.
## Overview
Health score configuration is managed from **Settings > Health Scores**. The configuration page has three tabs: Configuration, Test, and History.
## Creating a config
New configs start with a three-step wizard:
Score **all customers** or a specific **segment**. You can have one all-customers config plus one per segment (a segment can only be bound to one config). Picking a segment shows a live count of matching customers.
Set the score-range buckets and category weights (details below).
Click **Auto-configure** and AI generates **risk signals** and **growth signals** tailored to your organization and connected tools. They're editable as plain text — refine or regenerate as needed.
***
## Score Buckets
The score bucket bar at the top defines four risk levels that map score ranges to labels and colors.
* **Drag the dividers** between buckets to adjust score ranges
* **Click a label** to rename it
* Buckets must cover the full 0-100 range without gaps
Default buckets: Critical (0-24), At Risk (25-49), Medium (50-74), Healthy (75-100).
***
## Category Weights
Sliders control how much each category contributes to the overall score. Five categories are available:
* **Revenue**
* **Product Usage**
* **Engagement**
* **Support**
* **Market Signals**
Each category has an enable/disable toggle. Disabled categories are excluded from the calculation. Weights for enabled categories must total exactly 100%.
***
## Metric Configuration
Each enabled category contains individual metrics that can be toggled on or off. Expand a category section to see its available metrics.
### Threshold Editor
Each metric (except Market Signals) uses three threshold values that create four scoring buckets. Click the edit button on a metric to configure:
* **Three threshold values** - Define the boundaries between Critical, At Risk, Medium, and Healthy
* **Direction** - Whether higher values are better (e.g., MRR) or lower values are better (e.g., open tickets)
### Time Periods
Metrics that measure activity over time support configurable lookback periods:
* **Product Usage** - 30d, 60d, 90d, 180d, 1y
* **Engagement / Support** - 30d, 90d
### Product Usage Scoring Methods
Product usage metrics support four scoring methods:
| Method | Description |
| ----------------------- | -------------------------------------------------------- |
| **Trend + Volume** | Combines usage volume with trend direction (recommended) |
| **Absolute Value** | Score based on raw usage numbers |
| **Growth Percentage** | Score based on percentage change vs previous period |
| **Absolute Difference** | Score based on change in units vs previous period |
### Market Signals
Market Signals scoring is automatic based on detected signals. Positive signals (funding, growth) improve the score, while negative signals (layoffs, financial trouble) reduce it. No threshold configuration is needed.
### Orphaned Metrics
If a usage metric was configured but its data source is removed, it is flagged with a warning badge so you can update the configuration.
***
## Saving and Publishing
The configuration supports a draft/publish workflow:
* **Save Draft** - Saves your changes without affecting live scores
* **Publish** - Activates the configuration for the customers it scopes (all customers, or its segment). Scores calculate on the next daily run.
* **Reset** - Reverts unsaved changes to the last saved state
An "Unsaved" indicator appears when you have pending changes.
### Publishing
When you publish:
1. A dialog prompts for a **version name** (required) and **change description** (required for subsequent versions)
2. The previous published version is archived
3. A new version number is assigned
4. All future health score calculations use the new configuration
Publishing affects every customer the config scopes. Use the Test tab to validate your configuration before publishing.
# Interpreting Scores
Source: https://docs.quivly.ai/health-scores/interpreting-scores
How to read and act on customer health scores
## Overview
Health scores provide a composite view of customer health, but the category breakdown is where actionable insight lives. This page covers how to read scores effectively.
***
## Reading the Score
The overall score (0-100) maps to a risk level based on your configured score buckets. By default:
| Risk Level | Range | Suggested Action |
| ------------ | ------ | -------------------------------------------- |
| **Healthy** | 75-100 | Maintain cadence, explore expansion |
| **Medium** | 50-74 | Monitor trends, standard touchpoints |
| **At Risk** | 25-49 | Increase engagement, address specific issues |
| **Critical** | 0-24 | Urgent intervention needed |
***
## Using the Category Breakdown
The overall score is a starting point. Click into the Health Score tab on any customer to see the category breakdown and identify which area is driving the score up or down.
**What to look for:**
* **Lowest category score** - This is where to focus intervention
* **Score vs weight mismatch** - A low score in a heavily weighted category has outsized impact
* **Category with the most change** - Use the trend indicator to spot which areas are shifting
***
## Understanding Trends
On the Health Score tab, the history chart shows score changes over time:
* **Gradual decline** over weeks suggests a real trend that needs attention
* **Sudden drop** may indicate a specific event (e.g., spike in support tickets, missed renewal)
* **Score change at a version marker** indicates a configuration change, not a change in customer behavior
***
## When Scores Don't Match Expectations
If a score doesn't align with your knowledge of the customer:
* **Check for missing data** - A disconnected integration or missing usage data can skew scores
* **Review individual metrics** - Use the Test tab or the score breakdown to see which metrics are contributing unexpected values
* **Consider timing** - New customers in onboarding may have low scores that improve as they ramp up
# Overview
Source: https://docs.quivly.ai/health-scores/introduction
Understanding customer health scores in Quivly
## What are Health Scores?
Health scores are automated assessments (0-100) of how healthy your customer relationships are. Quivly calculates a score for each customer by analyzing data across five categories: Revenue, Product Usage, Engagement, Support, and Market Signals.
***
## Score Categories
Each category measures a different dimension of customer health:
| Category | What It Measures |
| ------------------ | ------------------------------------------------- |
| **Revenue** | MRR, outstanding balances, renewal timing |
| **Product Usage** | Product activity metrics from your data warehouse |
| **Engagement** | Call frequency and recency |
| **Support** | Ticket volume, resolution time, response time |
| **Market Signals** | External signals like funding, hiring, layoffs |
Each category receives a score (0-100) and a configurable weight. The overall health score is the weighted sum of all category scores.
***
## Risk Levels
Scores are mapped to risk levels using configurable score buckets. The defaults are:
| Risk Level | Default Range | Color |
| ------------ | ------------- | ------ |
| **Healthy** | 75-100 | Green |
| **Medium** | 50-74 | Amber |
| **At Risk** | 25-49 | Orange |
| **Critical** | 0-24 | Red |
Bucket ranges and labels are fully customizable in the health score configuration.
***
## How Scores are Calculated
1. **Metric scores** - Each enabled metric is scored 0-100 based on its value relative to configured thresholds
2. **Category scores** - Metrics within a category are averaged to produce a category score
3. **Overall score** - Category scores are combined using their configured weights (must total 100%)
**Example:**
| Category | Score | Weight | Contribution |
| -------------- | ----- | -------- | ------------ |
| Revenue | 85 | 30% | 25.5 |
| Product Usage | 60 | 25% | 15.0 |
| Engagement | 70 | 20% | 14.0 |
| Support | 40 | 15% | 6.0 |
| Market Signals | 80 | 10% | 8.0 |
| **Total** | | **100%** | **68.5** |
***
## Where Health Scores Appear
* **Customer list** - Health score and risk level columns with trend indicators
* **Customer detail page** - Health Score tab with history chart and category breakdown
* **Overview tab** - Health score summary widget on every customer's overview
# Metrics Guide
Source: https://docs.quivly.ai/health-scores/metrics-guide
How health score metrics are scored and combined
## Overview
Each health score metric is scored from 0-100 based on its current value and configured thresholds. This page explains the scoring mechanics.
***
## Thresholds and Buckets
Each metric uses **three threshold values** that divide the score range into four buckets. The bucket a metric falls into determines its score.
**Example** - "Days Since Last Call" with thresholds \[14, 30, 60] and direction "lower is better":
| Value | Bucket | Score |
| ---------- | -------- | ------ |
| 0-14 days | Healthy | 75-100 |
| 15-30 days | Medium | 50-74 |
| 31-60 days | At Risk | 25-49 |
| 60+ days | Critical | 0-24 |
***
## Direction
Each metric specifies whether higher or lower values indicate better health:
| Direction | Examples |
| -------------------- | ------------------------------------------------------------------------ |
| **Higher is better** | MRR, call frequency, product usage |
| **Lower is better** | Days since last call, open tickets, outstanding balance, resolution time |
***
## Available Metrics by Category
### Revenue
* MRR (Monthly Recurring Revenue)
* Outstanding invoice balance
* Days until renewal
### Product Usage
Metrics are automatically discovered from your data warehouse integration. Available metrics depend on what usage data you send to Quivly.
Each usage metric supports a **scoring basis** (Trend + Volume, Absolute Value, Growth Percentage, or Absolute Difference) and a **time period** (30d to 1y).
### Engagement
* Calls (volume over a configurable time period)
* Days since last call
* Call sentiment
* Slack conversations (volume over a configurable time period)
* Days since last Slack message
* Slack sentiment
### Support
* Open ticket count
* Ticket volume (configurable time period)
* First response time
* Resolution time
### Market Signals
Scoring is automatic. Positive signals improve the score, negative signals reduce it. Configure the lookback period (30d or 90d).
***
## How Scores Combine
1. Each metric receives a score (0-100) based on its value and thresholds
2. Metrics within a category are averaged to produce a **category score**
3. Category scores are multiplied by their weights and summed to produce the **overall health score**
# Testing
Source: https://docs.quivly.ai/health-scores/testing-scores
Test health score configurations before publishing
## Overview
The Test tab in **Settings > Health Scores** lets you calculate a health score for any customer using either the published configuration or an unpublished draft, so you can validate changes before publishing.
***
## Running a Test
Use the customer search to find a customer by name or domain.
Choose between the current **Published** version or the **Unpublished Draft** (if one exists).
Click **Calculate** to run the health score computation for that customer.
***
## Test Results
The results display:
* **Score** - The calculated health score (0-100) with a color-coded risk level badge
* **Version** - Which configuration was used (Draft or published version number)
* **Progress bar** - Visual score position on a 0-100 scale
### Score Breakdown
A table shows how the score was computed:
| Column | Description |
| ---------------- | ----------------------------------------------------------- |
| **Category** | Revenue, Product Usage, Engagement, Support, Market Signals |
| **Score** | Individual category score (0-100) |
| **Weight** | Category weight percentage |
| **Contribution** | Weighted score contribution to the total |
### Metric Details
Expand any category row to see the individual metrics:
* **Metric label** - Name of the metric
* **Raw value** - The actual data value
* **Bucket** - Which scoring bucket the value falls into
* **Score** - The normalized metric score
# Version History
Source: https://docs.quivly.ai/health-scores/version-history
Track health score configuration changes over time
## Overview
The History tab in **Settings > Health Scores** shows all published configuration versions. Each time you publish a new configuration, the previous one is archived and a new version is created.
***
## Version List
The history table displays all versions with the following columns:
| Column | Description |
| ----------------------- | -------------------------------------------------- |
| **Version** | Version number (e.g., v1, v2) |
| **Name** | Version name provided at publish time |
| **Category Weightages** | Weight distribution across categories |
| **Metrics** | Count of enabled metrics and product usage metrics |
| **Status** | Active (current) or Archived |
| **Published At** | When the version was archived, and by whom |
Click any row to view its full configuration details.
***
## Version Details
The detail modal shows the complete configuration snapshot:
* **Version notes** - Name, what changed, and expected impact (if provided at publish time)
* **Score buckets** - Label, score range, and color for each risk level
* **Category weightages** - Percentage weight for each category with a total row
* **Metrics summary** - Total enabled metrics with a count per category
* **Metadata** - Created/updated/archived timestamps and who made the changes
***
## Version Markers
On the customer Health Score tab, version changes appear as **dashed vertical lines** on the history chart. These markers help distinguish score changes caused by configuration updates from changes caused by actual customer behavior.
# How Quivly Works
Source: https://docs.quivly.ai/how-quivly-works
Data flows in from your connected systems, gets unified into one customer model, and AI features work on top of that model.
Quivly has three layers. Data comes in, gets organized around customers, and AI acts on it.
## 1. Data in
You connect the systems you already use:
* **CRM** (Salesforce, HubSpot) — customers, contacts, opportunities, owners
* **Billing** (Stripe) — subscriptions, invoices, MRR
* **Support** (Pylon) — tickets, response times
* **Calls** (Fireflies, Fathom, Granola) — transcripts and summaries
* **Slack** — customer channel conversations
* **Product usage** — from your warehouse (Snowflake, BigQuery), PostHog, or pushed directly via the [Usage API](/integrations/product-usage/api-overview)
Quivly reads from these systems. It never writes back to your CRM, billing, or support tools on its own — outbound messages (like a Slack message or email from an agent) only happen through steps you configure and approve. See [security and compliance](/security).
## 2. One customer model
Records from different systems are matched to a single customer — a Stripe customer, a HubSpot company, and a Slack channel all land on the same profile. You control how fields map through [field mappings](/field-mappings/introduction), and you can extend the model with [custom fields and objects](/data-models/custom-fields).
Think of it like a filing system that files every new document under the right customer automatically.
## 3. AI on top
Every AI feature reads from the same unified model:
| Feature | What it does |
| -------------------------------------------- | ----------------------------------------------------------------------------------- |
| [Health scores](/health-scores/introduction) | Scores each customer across revenue, usage, engagement, support, and market signals |
| [Ask Quivly](/product/ask-quivly) | Answers questions across all connected data, in-app or in Slack |
| [Agents](/product/agents) | Runs automated workflows on triggers like record changes or health drops |
| [Actions](/product/actions) | Drafts next steps for you to review and send |
| [Notebooks](/product/notebooks) | Writes customer documents (QBR prep, handoffs) from live data |
| [AI fields](/product/ai-fields) | Computes field values from each customer's data on a schedule |
| [Skills](/product/skills) | Your reusable instructions that steer all of the above |
Developers can also point external AI tools (Claude, Cursor, ChatGPT) at the same data through the [Quivly MCP server](/developers/mcp-server).
## FAQ
No. Data integrations are read-only. Outbound activity (Slack messages, emails, calendar invites) only happens through agent steps or actions that you configure, and you can require human review before anything sends. See [security and compliance](/security).
Quivly links records across systems using identifiers like domains and external IDs, and you can review and adjust the linking. See [cross-system linking](/field-mappings/cross-system-linking).
No. Each feature works with whatever data you've connected — more sources just make answers and scores richer. Health score categories with no connected source are simply disabled.
# Agent Tools
Source: https://docs.quivly.ai/integrations/agent-tools/composio
Connect external apps that Quivly agents can act through — Gmail, Google Calendar, Calendly — and see every tool call in an activity log.
Agent tools are apps Quivly's AI can **act through** — as opposed to data sources it reads from. They live under **Settings → Integrations → Agents**.
Today that's [Gmail](/integrations/communication/gmail), [Google Calendar](/integrations/communication/google-calendar), and [Calendly](/integrations/communication/calendly) — all per-user OAuth connections — plus read lookups against connected CRM data inside agent workflows.
## How they're used
* **Agents** use the **App Action** step: pick a connected app, pick an operation, and map fields. For per-user apps you choose who it runs as — the record's CSM owner, a specific teammate, or the agent's publisher.
* **Actions** use them in the Execute modal — the email or calendar draft sends through the chosen person's connection.
Each app's detail page shows its available **Tools** and an **Activity** log of every call made, so you can audit what the AI actually did.
## FAQ
No. They perform actions (send, create, look up on demand). Data syncing is what [data-source integrations](/integrations/introduction) do.
No — sending as a person requires that person's own connection. Agents can be configured to fall back to the publisher's connection.
# External MCP Servers
Source: https://docs.quivly.ai/integrations/agent-tools/external-mcp
Connect any third-party MCP server to Quivly so your agents and Ask Quivly can use its tools — with per-tool enable switches and write tools off by default.
If a tool your team uses exposes an [MCP](https://modelcontextprotocol.io) server, you can plug it into Quivly and its tools become available to [agents](/product/agents), [skills](/product/skills), and [Ask Quivly](/product/ask-quivly).
This is the mirror image of the [Quivly MCP server](/developers/mcp-server): that one lets external AIs use Quivly's data; this one lets Quivly's AI use external tools.
## Connecting a server
Go to **Settings → Integrations → MCP** and paste the server's HTTPS URL. Quivly probes it and detects what auth it needs.
Depending on the server: paste an API token (stored encrypted, never shown again), or complete the server's OAuth flow in a popup. Servers that require a pre-registered OAuth app accept a client ID and secret under Advanced settings.
Confirm, and tool discovery runs automatically.
## Tool controls
* **Read tools are enabled by default.**
* **Write tools are off until you switch them on**, tool by tool.
Enabled tools then show up for agents and Ask Quivly to call on your organization's behalf.
## FAQ
You control exactly which tools are enabled, and anything that writes stays off unless you enable it. Credentials are stored encrypted; OAuth logins never pass through Quivly.
Any MCP server reachable over HTTPS with no auth, bearer-token auth, or MCP OAuth.
# Stripe
Source: https://docs.quivly.ai/integrations/billing/stripe
Connect Stripe to sync revenue data, subscriptions, and payment information
**Who is this guide for?** This guide is for **administrators** setting up the Stripe integration. You'll need Stripe admin or developer access to create API keys.
***
## What Data Syncs from Stripe?
| Stripe Object | Maps to Quivly Object | What Syncs |
| ----------------- | --------------------- | ----------------------------------------- |
| **Customers** | Customers | Customer name, email, metadata, balance |
| **Subscriptions** | Subscriptions | Plan details, status, current period, MRR |
| **Invoices** | Invoices | Amount, status, due date, payment status |
| **Products** | Billing Products | Product name, description, pricing |
**Sync:** Continuous — changes stream in via webhooks
***
## Prerequisites
* Active Stripe account
* Access to authorize the connection (Admin or Developer role)
***
## Step-by-Step Setup
Go to **Settings** → **Integrations**, click the **Stripe** card, and open the **Configure** tab.
Complete the embedded connection flow — sign in to Stripe and approve access.
Quivly only reads data. We never create, update, or charge customers in Stripe.
1. Check the **Logs** tab to monitor sync activity
2. Once data arrives, open a customer profile
3. Go to the **Revenue** tab to verify Stripe data appears
***
## Customer Matching
Quivly uses email domain matching to link Stripe customers with CRM customers.
**Example:**
* Stripe customer with email `billing@acme.com`
* Salesforce account with domain `acme.com`
* Result: Matched as the same customer
Customers with generic email domains (gmail.com, yahoo.com) may not match reliably. For better matching, store CRM customer IDs in Stripe customer metadata.
# Fathom
Source: https://docs.quivly.ai/integrations/call-recordings/fathom
Connect Fathom to sync call recordings, transcripts, and meeting insights
## Overview
The Fathom integration syncs call recordings into Quivly. Calls are automatically matched to customers by participant email domain.
***
## What Syncs
**Object:** Meetings
Each meeting includes:
* Full transcript with speaker identification
* Date, duration, participants, meeting title
* AI-generated summary and highlights
* Action items and follow-ups
* Team and team member information
**Sync:** Continuous — new calls arrive via webhooks
***
## Prerequisites
* Fathom account with admin access to generate an API key
* Call recordings already available in Fathom
***
## Setup
Go to **Settings** → **Integrations**, click the **Fathom** card, and open the **Configure** tab.
Log in to your Fathom account, click **Settings**, scroll down to **API Access**, and create a new API key.
Paste your Fathom API key into Quivly when prompted.
Choose the meeting data you want to sync and select the specific fields to integrate with Quivly.
Click **Install** to complete the setup and begin the integration process.
Navigate to the **Logs** tab to see when your meeting data starts flowing in and monitor sync progress.
# Fireflies
Source: https://docs.quivly.ai/integrations/call-recordings/fireflies
Connect Fireflies to sync call transcripts and sentiment
## Overview
The Fireflies integration syncs call recordings into Quivly. Calls are automatically matched to customers by participant email domain.
***
## What Syncs
**Object:** Calls
Each call includes:
* Transcript with speaker identification
* Date, duration, participants, meeting title
* AI-generated summary and key topics
* Sentiment (positive, neutral, negative)
* Action items
**Sync:** Continuous — new calls arrive via webhooks
***
## Prerequisites
* Fireflies admin access to generate an API key
* Call recordings already available in Fireflies
***
## Setup
Go to **Settings** → **Integrations**, click the **Fireflies** card, and open the **Configure** tab.
Log in to your Fireflies account at [app.fireflies.ai](https://app.fireflies.ai), navigate to **Settings** → **Developer Settings** → **API Key**, and copy your API key.
Paste your Fireflies API key into Quivly when prompted.
Choose the call recording data you want to sync and select the specific fields to integrate with Quivly.
Click **Install** to complete the setup and begin the integration process.
Navigate to the **Logs** tab to see when your call data starts flowing in and monitor sync progress.
# Granola
Source: https://docs.quivly.ai/integrations/call-recordings/granola
Connect Granola to sync AI meeting notes into Quivly, matched to the right customer automatically.
Granola syncs your meeting notes into Quivly as call records. Participants are matched to customers by email domain, so each meeting lands on the right customer's Calls tab automatically.
## Connecting
1. Go to **Settings → Integrations → Granola**.
2. Open the **Configure** tab and complete the embedded OAuth connection.
An **Integration Guide** tab on the same page walks through setup details.
## What syncs
Granola notes flow into Quivly's call recordings: they appear on the customer's [Calls tab](/customer-views/calls-tab), are searchable in [Ask Quivly](/product/ask-quivly), and count toward engagement in [health scores](/health-scores/introduction). Sync is webhook-driven and read-only — Quivly never writes to Granola.
## FAQ
By resolving participants' email domains against your customers' domains, the same way as other call recording sources.
# Calendly
Source: https://docs.quivly.ai/integrations/communication/calendly
Connect your Calendly so Quivly agents can look up your bookings. Per-user connection.
Calendly is an **agent tool** with a per-user connection. Once connected, [agents](/product/agents) and [skills](/product/skills) can read your bookings — for example, to check whether a customer already has time scheduled before drafting an outreach.
## Connecting
1. Go to **Settings → Integrations → Calendly**.
2. Click **Connect** — a Calendly sign-in popup opens.
3. Approve access.
Each teammate connects their own account. The integration page shows the available tools and an activity log.
## FAQ
No — this connection powers agent lookups, not a data sync into the customer model.
# Gmail
Source: https://docs.quivly.ai/integrations/communication/gmail
Connect your Gmail so Quivly agents and actions can draft and send email as you. Per-user connection; no inbox syncing.
Gmail is an **agent tool**, not a data source: connecting it doesn't sync your inbox into Quivly. It lets [agents](/product/agents) and [actions](/product/actions) send email as you — for example, a drafted check-in email in the Actions inbox that goes out from your own address.
## Connecting
Each teammate connects their own account:
1. Go to **Settings → Integrations → Gmail**.
2. Click **Connect** — a Google sign-in popup opens.
3. Approve access.
Your connection is yours alone; a teammate connecting theirs doesn't connect yours. The integration page shows the tools available and an activity log of what's been run.
## Where it's used
* **Actions** — email steps in the Execute modal can send as "My account" once you're connected.
* **Agents** — App Action steps can send as the record's CSM owner, a specific teammate, or the agent's publisher (each of whom needs their own connection).
## FAQ
Connecting Gmail here does not create an inbox sync — it's used to act (draft/send) through your account when a step you review or configure calls for it.
The step prompts with a Connect button, and agents can be configured to fall back to the publisher's connection.
# Google Calendar
Source: https://docs.quivly.ai/integrations/communication/google-calendar
Connect your Google Calendar so Quivly agents and actions can create events as you — with attendees pulled from customer contacts.
Google Calendar is an **agent tool**: it doesn't sync your calendar into Quivly. It lets [agents](/product/agents) and [actions](/product/actions) create events as you — like scheduling a check-in call directly from a drafted recommendation, with attendees picked from the customer's contacts.
## Connecting
Each teammate connects their own account:
1. Go to **Settings → Integrations → Google Calendar**.
2. Click **Connect** — a Google sign-in popup opens.
3. Approve access.
The connection is per user. The integration page lists the available tools and an activity log.
## Where it's used
* **Actions** — calendar event steps open a composer with date, time, duration, and attendees from the customer's contacts.
* **Agents** — App Action steps can create events as the CSM owner, a specific teammate, or the agent's publisher.
## FAQ
This connection is for creating events through steps you configure or review — there's no calendar sync feeding Quivly's customer data.
# Slack
Source: https://docs.quivly.ai/integrations/communication/slack
Install the Quivly Slack app to track customer channel conversations, get alerts, use the Ask Quivly bot, and optionally send messages as yourself.
Slack is Quivly's two-way integration: it reads conversations from the channels you map to customers, and it's how Quivly talks to your team — alerts, agent messages, and the [Ask Quivly bot](/product/ask-quivly-slack).
## Workspace install (admin)
Go to **Settings → Integrations → Slack** and install the Quivly app to your workspace via Slack's OAuth flow.
Map shared or account channels to the right customer. Messages in mapped channels feed that customer's conversation history and sentiment.
Once installed, your team can DM or @mention the bot anywhere, agents can post messages and DMs, and notifications flow to the channels you choose.
## Personal connection (any teammate)
Separately from the workspace bot, each teammate can connect a **personal Slack** ("send as yourself"). When an [agent](/product/agents) or [action](/product/actions) sends a Slack message, it can then send as that person instead of the bot. Connect or disconnect it from the Slack integration page — it's per user and doesn't reinstall the app.
## What Quivly reads
Messages in **mapped customer channels** are ingested for conversation intelligence — summaries, sentiment, and searchability in [Ask Quivly](/product/ask-quivly). Unmapped channels aren't ingested.
## FAQ
A Quivly admin with permission to install apps in your Slack workspace.
By default, as the Quivly bot. If you've connected your personal Slack, agents and actions can send as you when configured that way.
# HubSpot
Source: https://docs.quivly.ai/integrations/crm/hubspot
Connect HubSpot to sync customers, contacts, and deals
**Who is this guide for?** This guide is for **administrators** setting up the HubSpot integration. You'll need HubSpot admin access to authorize the OAuth connection.
***
## What Data Syncs from HubSpot?
| HubSpot Object | Maps to Quivly Object | What Syncs |
| -------------- | --------------------- | -------------------------------------------------------------- |
| **Companies** | Customers | Company name, domain, industry, create date, custom properties |
| **Contacts** | Contacts | Name, email, job title, phone, associated company |
| **Deals** | Opportunities | Deal name, amount, stage, close date, owner |
| **Owners** | External Users | Owner name, email (for assigning accounts) |
| **Meetings** | Call Recordings | Meeting details, matched to the customer |
**Sync:** Continuous — changes stream in via webhooks
***
## Prerequisites
* Active HubSpot account (Free tier works, but Professional/Enterprise recommended)
* Admin or Super Admin role in HubSpot
* Permission to install integrations and approve OAuth apps
***
## Step-by-Step Setup
1. Log in to Quivly
2. Click **Settings** in the left sidebar
3. Navigate to the **Integrations** tab
4. In the **CRM** section, find **HubSpot CRM**
5. Click the **HubSpot** card and open the **Configure** tab
1. Click **Connect to HubSpot**
2. You'll be redirected to HubSpot's authorization page
3. Log in to HubSpot if prompted
4. Select the HubSpot account you want to connect
5. Review the permissions and click **Connect app**
Quivly only requests **read permissions**. We never write data back to HubSpot.
Once connected, Quivly will begin syncing your HubSpot data.
**Estimated time:**
* Small accounts (\< 100 companies): 5-10 minutes
* Medium accounts (100-1,000 companies): 10-30 minutes
* Large accounts (1,000+ companies): 30-60 minutes
Check the **Logs** tab to monitor progress.
1. Check the integration status shows 🟢 **Healthy**
2. Navigate to **Customers** in the sidebar
3. Verify your HubSpot companies appear in the customer list
***
## Configuring Field Mappings
After the initial sync, you can customize how HubSpot properties map to Quivly fields.
1. Go to **Settings** → **Objects** → **Customers**
2. Navigate to the **Configuration** tab
3. Select **HubSpot CRM** as the integration source
4. Review and modify mappings as needed
5. Click **Save Mappings**
**Default mappings:**
| HubSpot Property | Quivly Field |
| ---------------- | -------------- |
| `name` | customer\_name |
| `domain` | domain |
| `industry` | industry |
| `createdate` | created\_at |
| `hs_object_id` | external\_id |
***
## Customer Matching
Quivly uses domain-based matching to link HubSpot companies to customers from other integrations (like Stripe).
**Example:**
* HubSpot company with domain `acme.com`
* Stripe customer with email `billing@acme.com`
* Result: Matched as the same customer
Ensure HubSpot companies have valid domains populated. Companies without domains won't match with other integrations.
# Salesforce
Source: https://docs.quivly.ai/integrations/crm/salesforce
Connect Salesforce to sync accounts, contacts, opportunities, and products
## Overview
The Salesforce integration syncs your CRM data into Quivly. Customers are matched across integrations by domain.
***
## What Syncs
| Object | Data |
| ----------------- | ---------------------------------------------------- |
| **Accounts** | Name, website, industry, type, custom fields |
| **Contacts** | Name, email, title, phone, associated account |
| **Opportunities** | Name, amount, stage, close date, owner |
| **Contracts** | Contract status, dates, linked opportunity and owner |
| **Users** | Name, email (for account assignments) |
**Sync:** Continuous — changes stream in via webhooks
***
## Prerequisites
* Salesforce admin access to authorize the OAuth connection
* API access enabled (included in Professional, Enterprise, and Unlimited editions)
***
## Setup
Go to **Settings** → **Integrations**, click the **Salesforce** card, and open the **Configure** tab.
You will be redirected to Salesforce to authenticate. Enter your credentials and authorize access.
Choose the Salesforce objects you want to sync and select the specific fields to integrate with Quivly.
Click **Install** to complete the setup and begin the integration process.
Once installed, the integration will automatically begin syncing your data from Salesforce.
Navigate to the **Logs** tab to see when your data starts flowing in and monitor sync progress.
# Integrations FAQ
Source: https://docs.quivly.ai/integrations/faq
Common questions about connecting data sources to Quivly — permissions, syncing, matching, and troubleshooting.
No. Data-source integrations are read-only. The only outbound activity is through agent tools (Slack, Gmail, Google Calendar) in steps your team configures. See [security and compliance](/security).
Data sources are connected org-wide by an admin from **Settings → Integrations**. Agent tools like Gmail and Calendly are connected individually by each teammate.
Three ways: connect your data warehouse ([Snowflake](/integrations/warehouses/snowflake) or [BigQuery](/integrations/warehouses/bigquery)), connect [PostHog](/integrations/product-usage/posthog), or push events from your backend to the [Usage Push API](/integrations/product-usage/api-overview).
Tiles like Zendesk, Intercom, Gong, Chargebee, Attio, Jira, Amplitude, and Mixpanel aren't connectable yet. Email [support@quivly.ai](mailto:support@quivly.ai) to prioritize one. For usage analytics tools, the Push API is usually a quick workaround.
By identifiers like email domains and external IDs — a Stripe customer, HubSpot company, and Slack channel resolve to the same profile. You can review and adjust links; see [cross-system linking](/field-mappings/cross-system-linking).
Open the integration's detail page — data-source integrations show sync activity and logs. Agent tools show a tool list and an activity log of calls instead (they don't sync data).
Yes — field mappings under **Settings → Objects** control how external fields map to Quivly's model, including custom fields. See [field mappings](/field-mappings/introduction).
# Integrations Overview
Source: https://docs.quivly.ai/integrations/introduction
Connect your CRM, billing, support, call recording, Slack, and product usage systems to Quivly. What's available, how connections work, and what data syncs.
Integrations feed Quivly's unified customer model. Connect a system once and its data flows into the right customer profile automatically.
All integrations live in **Settings → Integrations**.
## Available integrations
| Category | Available now | How it connects |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| CRM | [Salesforce](/integrations/crm/salesforce), [HubSpot](/integrations/crm/hubspot) | OAuth |
| Billing | [Stripe](/integrations/billing/stripe) | OAuth |
| Support | [Pylon](/integrations/support/pylon) | OAuth |
| Call recordings | [Fireflies](/integrations/call-recordings/fireflies), [Fathom](/integrations/call-recordings/fathom), [Granola](/integrations/call-recordings/granola) | OAuth |
| Communication | [Slack](/integrations/communication/slack) | OAuth (workspace bot + optional personal connection) |
| Agent tools | [Gmail](/integrations/communication/gmail), [Google Calendar](/integrations/communication/google-calendar), [Calendly](/integrations/communication/calendly) | OAuth, per user |
| Product usage | [Snowflake](/integrations/warehouses/snowflake), [BigQuery](/integrations/warehouses/bigquery), [PostHog](/integrations/product-usage/posthog), [Usage Push API](/integrations/product-usage/api-overview) | Credentials / API key |
| Developer | GitHub (for [skill import](/developers/github-skill-import)) | GitHub App install |
Tiles for Attio, Chargebee, Zendesk, Intercom, Gong, Jira, Amplitude, Mixpanel, Redshift, and Google Sheets appear in the app as **coming soon** — you can't connect them yet. Email [support@quivly.ai](mailto:support@quivly.ai) if one of these is blocking you.
## Two kinds of integrations
**Data sources** (CRM, billing, support, calls, warehouses, PostHog) sync records into Quivly — customers, contacts, opportunities, subscriptions, invoices, tickets, call transcripts, usage metrics. These are read-only: Quivly never writes back to them. Each has a detail page with sync logs.
**Agent tools** (Gmail, Google Calendar, Calendly) don't sync any data. They let [agents](/product/agents) and [actions](/product/actions) do things — send an email, create a calendar event — as the connected user. Each teammate connects their own account, so an agent can send as the account owner rather than a bot.
Slack is both: the workspace bot ingests conversations from mapped customer channels *and* sends messages, and teammates can optionally connect a personal Slack so messages send as them.
## After connecting
Open the integration's detail page to see sync activity and logs.
Data-source records map to Quivly's customer model. Review and customize under **Settings → Objects**. See [field mappings](/field-mappings/introduction).
Records from different systems are linked to the same customer. See [cross-system linking](/field-mappings/cross-system-linking).
## FAQ
No. Data-source integrations are read-only. Only agent tools (Gmail, Calendar, Slack) send anything outbound, and only through steps you configure. See [security and compliance](/security).
Data sources are connected once for the whole organization by an admin. Agent tools like Gmail and Calendly are connected per teammate, so outbound messages can be sent as a specific person.
Use your data warehouse (Snowflake or BigQuery), connect PostHog directly, or push events to the [Usage Push API](/integrations/product-usage/api-overview) from your own backend.
# Overview
Source: https://docs.quivly.ai/integrations/product-usage/api-overview
Push product usage events to Quivly directly over HTTP
**Who is this guide for?** Engineers who want to send product usage data to Quivly straight from their backend, instead of (or alongside) a data warehouse connection.
***
## What is the Push API?
The Push API lets your application send product usage events to Quivly over HTTP. Instead of Quivly querying your warehouse on a schedule, your backend **pushes** events — one at a time or in batches.
There are two ways to get product usage into Quivly:
Quivly queries your BigQuery or Snowflake on a schedule. Best when usage data already lives in a warehouse.
Your backend posts events to Quivly. Best when you want to push directly, without a warehouse. **(this section)**
You can use either method, or both.
***
## How to set it up
Go to **Settings → Objects → Product Usage → Configuration**. Create a configuration and choose **Push API** as the source.
Generate an API key in the panel. There is **one key per organization**, and it authenticates every request.
The panel shows your endpoint and a ready-to-run `curl` example with your key filled in.
Send your first call to the endpoint. Include **all the customer IDs you plan to send**, so the whole mapping is checked at once. Quivly verifies the event the moment it arrives — nothing is stored yet.
Once a test event has verified, click **Publish**. From then on, events you send are stored as product usage.
**Nothing is stored until you publish.** Before you publish, every call is verify-only: Quivly resolves the events against your customers and tells you what matched, but writes nothing.
***
## Key things to know
### Customer IDs must already be recognized
`external_customer_id` must be an ID Quivly already knows for that customer — typically the ID from a connected CRM or source (for example, a Salesforce or HubSpot ID). IDs Quivly doesn't recognize are **dropped** and returned in the response's `errors`. There is no separate mapping step for the API: send IDs your customers are already known by.
You can review which customers have sent usage, and the IDs Quivly recognizes for each, on the **Customer Mapping** tab of the configuration.
### Metrics are discovered automatically
You don't pre-declare metrics. Any `metric_key` you send is accepted. New metric keys appear in the configuration's metric list and roll up as **Sum** across periods by default — you can change a metric's rollup there.
### Re-sending replaces, it doesn't add
A value is stored per customer + metric + period + granularity. Sending the same combination again **replaces** the previous value — it is not added on top. Pre-aggregate to one value per customer / metric / period before sending.
***
Endpoint, request format, idempotency, rate limits, and response details.
# API Reference
Source: https://docs.quivly.ai/integrations/product-usage/api-reference
Endpoint, request format, and responses for the Push API
## Endpoint
```http theme={null}
POST https://app.quivly.ai/api/v1/usage/events
```
## Authentication
Send your organization API key as a bearer token. Quivly derives your organization from the key.
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
A missing or invalid key returns `401`.
***
## Request body
Send a batch of events. **1–1000** events per request.
```json theme={null}
{
"events": [
{
"external_customer_id": "001gL00000XR5jlQAD",
"metric_key": "api_calls",
"value": 18420,
"granularity": "daily",
"timestamp": "2026-06-11T00:00:00Z",
"properties": { "region": "us-east-1", "plan": "growth" }
}
]
}
```
### Event fields
| Field | Type | Required | Description |
| ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `external_customer_id` | string | **Yes** | An ID Quivly already recognizes for the customer (e.g. a CRM ID). Max 255 chars. Unrecognized IDs are dropped and listed in `errors`. |
| `metric_key` | string | **Yes** | The metric name, e.g. `api_calls`. Max 128 chars. New metric keys are accepted automatically. |
| `value` | number | **Yes** | The measured quantity. Must be a finite number. |
| `timestamp` | string | No | ISO 8601 timestamp of the usage (e.g. `2026-06-11T00:00:00Z`). Defaults to the time of ingestion when omitted. |
| `granularity` | string | No | One of `hourly`, `daily`, `weekly`, `monthly`. Defaults to `daily`. |
| `properties` | object | No | Free-form metadata stored with the event. Must be ≤ 4 KB. |
### Example request
```bash theme={null}
curl -X POST https://app.quivly.ai/api/v1/usage/events \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"events": [
{
"external_customer_id": "001gL00000XR5jlQAD",
"metric_key": "api_calls",
"value": 18420,
"granularity": "daily",
"timestamp": "2026-06-11T00:00:00Z"
},
{
"external_customer_id": "001gL00000YBlhZQAT",
"metric_key": "seats_active",
"value": 42
}
]
}'
```
***
## Idempotency
Sending the `Idempotency-Key` header makes retries safe. If a request with the same key has already been processed, Quivly **replays the stored response** instead of processing again, and adds the header `Idempotency-Replayed: true`.
```http theme={null}
Idempotency-Key: 7f3c1e2a-... (a unique UUID per request)
```
This header is optional but recommended — use it whenever a network error might cause your client to retry.
## Rate limits
Up to **1,000 requests per minute** per organization. Exceeding the limit returns `429` with a `Retry-After` header (seconds to wait).
## Verify mode and dry runs
Before you publish the configuration, every call is **verify-only** — events are resolved against your customers and reported, but nothing is stored. After publishing, you can still force a verify-only call by adding `?dry_run=true`:
```http theme={null}
POST https://app.quivly.ai/api/v1/usage/events?dry_run=true
```
***
## Response
A successful call returns `200` with a summary of what happened.
```json theme={null}
{
"success": true,
"data": {
"mode": "live",
"stored": true,
"inserted": 2,
"skipped": 0,
"summary": { "total": 2, "matched": 2, "unmatched": 0, "rejected": 0 },
"results": [
{
"external_customer_id": "001gL00000XR5jlQAD",
"metric_key": "api_calls",
"value": 18420,
"matched": true,
"customer_id": "a1b2c3d4-...",
"customer_name": "Acme Corp",
"metric_allowed": true,
"written": true
}
],
"errors": []
}
}
```
Before publishing (or with `?dry_run=true`), the same call returns `mode: "test"`, `stored: false`, `inserted: 0`, and each result's `written` is `false` — confirming the events resolved but were not saved.
### Response fields
| Field | Description |
| ------------------- | -------------------------------------------------------------- |
| `mode` | `live` when events were stored, `test` for a verify-only call. |
| `stored` | Whether events were written to product usage. |
| `inserted` | Number of events written. |
| `summary.total` | Events received. |
| `summary.matched` | Events whose `external_customer_id` matched a customer. |
| `summary.unmatched` | Events dropped because the customer ID wasn't recognized. |
| `results` | Per-event detail (first 100). |
| `errors` | Events that were dropped, with the reason (first 100). |
A dropped (unmatched) event appears in `errors` like this:
```json theme={null}
{ "index": 2, "external_customer_id": "unknown-id", "reason": "No customer matches this external_customer_id" }
```
***
## Errors
| Status | When | Body |
| ------ | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `401` | Missing or invalid API key | `{ "success": false, "error": "Invalid or missing API key", "code": "UNAUTHORIZED" }` |
| `422` | The payload failed validation | See **Validation errors** below |
| `422` | A live call where **every** event was dropped (none matched a customer) | `error: "No events could be ingested…"`, with the full summary under `details` |
| `429` | Rate limit exceeded | `{ "success": false, "error": "Too many requests", "code": "RATE_LIMITED" }` + `Retry-After` header |
### Validation errors
When the payload is malformed, Quivly returns `422` and points to the exact field paths that failed:
```json theme={null}
{
"success": false,
"error": "Invalid usage events payload",
"code": "VALIDATION_ERROR",
"details": {
"issues": [
{ "path": "events.0.value", "message": "Expected number, received string" },
{ "path": "events.1.metric_key", "message": "String must contain at least 1 character(s)" }
]
}
}
```
# PostHog
Source: https://docs.quivly.ai/integrations/product-usage/posthog
Connect PostHog with OAuth or an API key, map events to customers, and pull product usage metrics into Quivly on a schedule.
The PostHog integration pulls product usage out of PostHog and into each customer's [Usage tab](/customer-views/usage-tab) and [health score](/health-scores/introduction).
## Connecting
Go to **Settings → Integrations → PostHog**. Two options:
* **Connect with OAuth** — sign in to PostHog and approve.
* **Connect with an API key** — paste a Personal API key (`phx_...`) with `query:read` and `endpoint:read` scopes, choose your region (US Cloud, EU Cloud, or Self-hosted), and enter your instance URL if self-hosted.
## Configuring the sync
The sync itself is configured under **Product Usage** settings:
| Setting | What it does |
| ------------------- | ----------------------------------------------------------------------------------- |
| Project | Which PostHog project to pull from |
| Customer identifier | How PostHog events map to your customers — a group type or an event/person property |
| Events | Optional allowlist of events to include |
| Schedule | Daily, weekly, or manual only |
| Backfill | How many days of history to pull (1–365, default 90) |
Before publishing, click **Run test sync** — it dry-runs the last 7 days and shows which customers matched and which didn't, so you can fix the identifier mapping before any data lands. Once verified, **Publish** turns the scheduled sync on.
## FAQ
Daily metric values per customer (date, customer, metric, value) — not raw event streams.
Their identifier in PostHog doesn't resolve to a Quivly customer. Adjust the customer identifier setting or the external IDs on your customers.
Schedules are daily, weekly, or manual — daily is the fastest cadence.
# Pylon
Source: https://docs.quivly.ai/integrations/support/pylon
Connect Pylon to sync support tickets and customer issues
## Overview
The Pylon integration syncs support tickets into Quivly. Tickets are matched to customers by email domain.
***
## What Syncs
| Object | Data |
| ------------ | ------------------------------------------------ |
| **Issues** | Title, description, status, priority, timestamps |
| **Accounts** | Account name, metadata (for matching) |
| **Users** | Support agents (for assignee references) |
| **Contacts** | Requester details, linked to the customer |
**Sync:** Continuous — changes stream in via webhooks
***
## Prerequisites
* Pylon admin access to generate an API key
***
## Setup
1. Log in to Pylon
2. Go to **Settings** → **API Keys**
3. Click **Create API Key**
4. Set permissions to **Read-only**
5. Copy and save the API key
1. Go to **Settings** → **Integrations**
2. Find **Pylon** in Support section
3. Click the **Pylon** card and open the **Configure** tab
4. Paste your API key
5. Click **Test Connection**
6. Click **Save Integration**
# BigQuery
Source: https://docs.quivly.ai/integrations/warehouses/bigquery
Connect your BigQuery data warehouse to sync product usage metrics
**Who is this guide for?** This guide is for **administrators** setting up the BigQuery integration. You'll need admin access to your Google Cloud Platform project to create service accounts.
***
## What Data Syncs from BigQuery?
| Data Type | Maps to Quivly | What Syncs |
| ---------------------- | -------------- | ---------------------------------------------------- |
| **Usage Events** | Product Usage | Feature usage, page views, API calls, user actions |
| **Aggregated Metrics** | Usage Metrics | Daily active users, session counts, feature adoption |
| **Time-series Data** | Trend Analysis | Historical usage patterns for health scoring |
**Sync frequency:** Every 6 hours
***
## Prerequisites
* Active Google Cloud Platform project
* **Admin** or **Owner** role in GCP
* Permission to create service accounts
* BigQuery dataset with usage data ready
***
## Step-by-Step Setup
1. Go to [console.cloud.google.com](https://console.cloud.google.com)
2. Select your GCP project (or create one)
1. Navigate to **IAM & Admin** → **Service Accounts**
2. Click **Create Service Account**
3. Enter a name: `quivly-bigquery-reader`
4. Enter a description: "Service account for Quivly to read BigQuery usage data"
5. Click **Create and Continue**
Add the following roles to the service account:
| Role | Purpose |
| -------------------- | ------------------------------ |
| BigQuery Data Viewer | Read access to tables and data |
| BigQuery Job User | Ability to run queries |
Quivly only requires **read permissions**. We never write data to your BigQuery tables.
Click **Continue**, then **Done**.
1. In the service accounts list, find your `quivly-bigquery-reader` account
2. Click the three-dot menu → **Manage keys**
3. Click **Add Key** → **Create new key**
4. Select **JSON** as the key type
5. Click **Create**
6. The JSON key file will download to your computer
Store this JSON file securely. It contains credentials to access your BigQuery data. Never commit it to version control.
1. Go to **Settings** → **Integrations**, click the **BigQuery** card, and open the **Configure** tab
2. Click **New Connection** — BigQuery supports multiple named connections
3. Fill in: **Connection Name**, **Project ID**, **Dataset Name** (optional, needed for table browsing), and paste your **Service Account Key** JSON
4. Click **Test Connection** — it must succeed before you can connect
5. Click **Connect Database**
In the **Data Tables** section, click **Add Table** and pick the tables and columns that hold usage data.
Metric mapping (which columns become which metrics, customer identifier, sync schedule) is configured under **Settings → Objects → Product Usage**.
Open a customer profile and check the **Usage** tab once the first sync has run.
***
## BigQuery Hierarchy
Understanding the BigQuery structure helps with configuration:
* **Project:** Your GCP project (auto-detected from JSON key)
* **Dataset:** A collection of tables (you'll select this in Quivly)
* **Table:** Your usage data table (you'll map fields from here)
***
## Customer Matching
Quivly uses the customer ID field in your BigQuery table to link usage data with CRM customers.
**Example:**
* BigQuery row with `customer_id: "cust_123"`
* Salesforce account with external ID `cust_123`
* Result: Matched as the same customer
Ensure your BigQuery table has a reliable customer identifier that matches IDs in your CRM. Rows without valid customer IDs won't appear in customer profiles.
# Overview
Source: https://docs.quivly.ai/integrations/warehouses/overview
Connect your data warehouse to sync product usage metrics
**Who is this guide for?** This guide is for **administrators and data engineers** planning to connect a data warehouse to Quivly for product usage data.
There are two ways to send product usage to Quivly: connect a **data warehouse** (this guide) so Quivly queries it on a schedule, or push events directly with the [Push API](/integrations/product-usage/api-overview). Use whichever fits your stack — or both.
***
## Why Connect a Data Warehouse?
While CRM and billing integrations provide customer and revenue data, **data warehouse integrations** unlock your product usage data - the most powerful signal for predicting churn and identifying growth opportunities.
**What you can track:**
* Daily/weekly active users per customer
* Feature adoption and usage frequency
* API calls and volume metrics
* Product engagement trends
* Custom usage metrics specific to your product
**Impact on customer success:**
* Identify customers not using key features
* Detect usage declines before customers churn
* Find expansion opportunities (high usage = ready to upgrade)
* Understand which features drive retention
***
## Supported Data Warehouses
Quivly supports connections to the following data warehouses:
**Google Cloud Platform**
* Serverless, highly scalable
* Great for large datasets
* Authentication via service account
[Setup Guide →](/integrations/warehouses/bigquery)
**Snowflake Data Cloud**
* Enterprise-grade data warehouse
* Multi-cloud support
* Authentication via username/password
[Setup Guide →](/integrations/warehouses/snowflake)
Other warehouses (Redshift, PostgreSQL, MySQL, and more) aren't connectable in the app yet — email [support@quivly.ai](mailto:support@quivly.ai) if you need one, or push metrics from your own pipeline via the [Usage Push API](/integrations/product-usage/api-overview).
***
## Data Format: Long vs Wide
Before connecting your warehouse, understand the two common data formats for usage data:
### Long Format (Event-Based)
**Structure:** One row per event
**Use when:** You track individual user actions (clicks, page views, API calls)
**Example:**
```sql theme={null}
timestamp | customer_id | user_id | event_name | properties
--------------------+-------------+----------+---------------+------------
2024-01-15 10:23:45 | cust_123 | user_456 | page_viewed | {"page": "dashboard"}
2024-01-15 10:24:12 | cust_123 | user_456 | button_clicked| {"button": "export"}
2024-01-15 10:25:03 | cust_123 | user_789 | api_called | {"endpoint": "/customers"}
```
**Pros:**
* Flexible (can aggregate any way you want)
* Granular insights
* Easy to add new event types
**Cons:**
* Large table sizes
* Requires aggregation on every query
* Higher query costs
### Wide Format (Aggregated Metrics)
**Structure:** One row per time period with metrics as columns
**Use when:** You pre-aggregate usage data (daily/weekly rollups)
**Example:**
```sql theme={null}
date | customer_id | daily_active_users | api_calls | reports_generated
-----------+-------------+-------------------+-----------+------------------
2024-01-15 | cust_123 | 12 | 450 | 8
2024-01-15 | cust_456 | 5 | 120 | 2
2024-01-16 | cust_123 | 15 | 523 | 12
```
**Pros:**
* Faster queries (no aggregation needed)
* Smaller table sizes
* Lower query costs
**Cons:**
* Less flexible (metrics fixed)
* Must decide aggregations upfront
* Harder to add new metrics
**Recommendation:** Use **wide format** if you already aggregate usage in your ETL pipeline. Use **long format** if you want maximum flexibility and have raw event data.
See detailed examples in the [BigQuery Integration Guide](/integrations/warehouses/bigquery#understanding-data-formats-long-vs-wide).
***
## Prerequisites for All Warehouses
Before connecting any data warehouse:
Ensure you have usage data in a table with:
* **Customer identifier** (customer ID, account ID, or domain)
* **Timestamp or date** field
* **Event names or metric columns**
* Optional: User identifier, event properties
Run a test query to verify data exists and is structured correctly.
For security, create a dedicated user/service account with **read-only** permissions:
**BigQuery:** Service account with "BigQuery Data Viewer" role
**Snowflake:** Database user with SELECT permission on usage tables
Never give Quivly write permissions. Read-only access ensures we can't accidentally modify your data.
Verify Quivly can reach your data warehouse:
* If cloud-hosted: Usually no firewall changes needed
* If self-hosted: Whitelist Quivly's IP addresses
* If VPN/private network: Set up secure tunnel or VPN connection
Contact support for Quivly's IP addresses to whitelist.
Sync schedule is set later, in the usage mapping config under **Settings → Objects → Product Usage**:
| Frequency | Best For | Query Costs |
| ---------- | ----------------------------------- | ----------- |
| **Hourly** | Near real-time tracking | Higher |
| **Daily** | Cost-effective, sufficient for most | Lower |
| **Weekly** | Slow-moving metrics | Lowest |
| **Manual** | Infrequent updates, testing | Lowest |
Start with **daily syncs**. You can always increase frequency later.
***
## Sync Behavior Across Warehouses
### How Syncs Work
All warehouse integrations follow the same pattern:
**Initial Sync:**
1. Quivly queries your usage table for the last 90 days (configurable)
2. Data is ingested and processed
3. Usage metrics are calculated per customer
4. Health scores are updated
**Incremental Syncs:**
1. Quivly queries only new data since last sync (using timestamp/date field)
2. New data is appended
3. Metrics are recalculated
4. Health scores are updated
**Deduplication:**
* **Long format:** Deduplicates based on (timestamp, customer\_id, user\_id, event\_name)
* **Wide format:** Deduplicates based on (date, customer\_id) - newer values overwrite
### Query Examples
**Long format incremental query:**
```sql theme={null}
SELECT timestamp, customer_id, user_id, event_name, properties
FROM your_table
WHERE timestamp > '2024-01-15 14:30:00 UTC'
ORDER BY timestamp ASC
LIMIT 10000;
```
**Wide format incremental query:**
```sql theme={null}
SELECT date, customer_id, daily_active_users, api_calls, reports_generated
FROM your_table
WHERE date > '2024-01-15'
ORDER BY date ASC;
```
***
## Security and Permissions
### What Permissions Does Quivly Need?
| Warehouse | Required Permissions | Why |
| -------------- | ------------------------------------------------------------------------ | --------------------------------------- |
| **BigQuery** | `bigquery.tables.get`, `bigquery.tables.getData`, `bigquery.jobs.create` | Read table schema, query data, run jobs |
| **Snowflake** | `SELECT` on usage tables | Query usage data |
| **PostgreSQL** | `SELECT` on usage tables | Query usage data |
| **MySQL** | `SELECT` on usage tables | Query usage data |
| **Redshift** | `SELECT` on usage tables | Query usage data |
### Data Security
**How Quivly protects your data:**
* Read-only access (no write permissions)
* Encrypted connections (TLS/SSL)
* Credentials stored encrypted at rest
* Row-level security (organization isolation)
* No data shared across customers
**What data is synced:**
* Only usage data from tables you configure
* No PII unless explicitly mapped
* Data is aggregated (not raw event-level details)
**What data is NOT synced:**
* Other tables or schemas
* User passwords or sensitive fields
* Financial transaction details (unless explicitly configured)
***
**Need help choosing a warehouse or setting up your data?**
* Email support: [support@quivly.ai](mailto:support@quivly.ai)
* Book a call: [Schedule onboarding](https://cal.com/chandrika)
* BigQuery guide: [BigQuery Setup →](/integrations/warehouses/bigquery)
# Snowflake
Source: https://docs.quivly.ai/integrations/warehouses/snowflake
Connect your Snowflake data warehouse to sync product usage metrics
**Who is this guide for?** This guide is for **administrators and data engineers** setting up Snowflake. You'll need admin access to your Snowflake account (ACCOUNTADMIN or SECURITYADMIN role).
***
## What You'll Need
Before you begin, ensure you have:
* **Admin access** to your Snowflake account (ACCOUNTADMIN or SECURITYADMIN role)
* **Permissions** to create users, roles, and grant warehouse access
* **Knowledge** of which databases and schemas contain your customer usage data
***
## Configuration Requirements
Quivly requires the following information to connect:
| Configuration | Description |
| ----------------------- | ------------------------------------------------------------- |
| **Connection Name** | A label for this connection in Quivly |
| **Account** | Your Snowflake account identifier (e.g., `xy12345.us-east-1`) |
| **Warehouse** | The compute warehouse for queries |
| **Database** | The database containing usage data |
| **Schema** | Schema to use (default `PUBLIC`) |
| **Role** | Snowflake role to use (default `PUBLIC`) |
| **Username / Password** | The dedicated Quivly service user's credentials |
***
## Setup Instructions
Run the following SQL in your Snowflake worksheet:
```sql theme={null}
-- Create a dedicated role for Quivly
CREATE ROLE IF NOT EXISTS QUIVLY_READER_ROLE;
-- Grant usage on the warehouse Quivly will use
GRANT USAGE ON WAREHOUSE TO ROLE QUIVLY_READER_ROLE;
```
Grant read-only access to the databases and schemas containing your customer data:
```sql theme={null}
-- Grant access to a specific database
GRANT USAGE ON DATABASE TO ROLE QUIVLY_READER_ROLE;
-- Grant access to schemas within the database
GRANT USAGE ON ALL SCHEMAS IN DATABASE TO ROLE QUIVLY_READER_ROLE;
GRANT USAGE ON FUTURE SCHEMAS IN DATABASE TO ROLE QUIVLY_READER_ROLE;
-- Grant SELECT on tables and views
GRANT SELECT ON ALL TABLES IN DATABASE TO ROLE QUIVLY_READER_ROLE;
GRANT SELECT ON FUTURE TABLES IN DATABASE TO ROLE QUIVLY_READER_ROLE;
GRANT SELECT ON ALL VIEWS IN DATABASE TO ROLE QUIVLY_READER_ROLE;
GRANT SELECT ON FUTURE VIEWS IN DATABASE TO ROLE QUIVLY_READER_ROLE;
```
For tighter security, scope these grants to specific schemas rather than the entire database.
```sql theme={null}
-- Create a dedicated user for Quivly
CREATE USER IF NOT EXISTS QUIVLY_SERVICE_USER
PASSWORD = ''
DEFAULT_ROLE = QUIVLY_READER_ROLE
DEFAULT_WAREHOUSE =
MUST_CHANGE_PASSWORD = FALSE;
-- Assign the role to the user
GRANT ROLE QUIVLY_READER_ROLE TO USER QUIVLY_SERVICE_USER;
```
Use a strong, unique password. The connection form authenticates with username and password.
Your account identifier is in your Snowflake URL:
**Format:** `https://.snowflakecomputing.com`
**Examples:**
* URL: `https://xy12345.us-east-1.snowflakecomputing.com` → Account: `xy12345.us-east-1`
* URL: `https://mycompany.snowflakecomputing.com` → Account: `mycompany`
Include the region if present (e.g., `xy12345.us-east-1`).
1. Go to **Settings → Integrations**, click the **Snowflake** card, and open the **Configure** tab
2. Fill in the connection name, account, warehouse, database, schema, role, username, and password
3. Click **Test Connection** — it must succeed before you can connect
4. Click **Connect Database**
Metric mapping (which columns become which metrics, customer identifier, sync schedule) is configured afterward under **Settings → Objects → Product Usage**.
***
## Snowflake Structure
Snowflake organizes data in a three-level hierarchy:
* **Database** — Top-level container for your data
* **Schema** — Logical grouping of tables, views, and objects
* **Table/View** — Your actual data with rows and columns
Example: `ANALYTICS_DB` → `PRODUCT` → `EVENTS`
***
## Troubleshooting
Verify that `QUIVLY_READER_ROLE` has proper grants:
```sql theme={null}
SHOW GRANTS TO ROLE QUIVLY_READER_ROLE;
```
Ensure USAGE grants on warehouse, database, and schema, plus SELECT on tables.
Ensure your Snowflake account allows connections from Quivly's IP addresses. Check **Admin → Security → Network Policies** if you have IP allowlisting enabled.
Contact support for Quivly's IP addresses.
Confirm tables exist in the granted schemas and that FUTURE grants are in place for newly created tables.
The warehouse may be set to auto-suspend. Either increase the auto-suspend timeout or ensure the warehouse is running when Quivly syncs. Quivly will attempt to resume suspended warehouses automatically if the user has OPERATE privileges:
```sql theme={null}
GRANT OPERATE ON WAREHOUSE TO ROLE QUIVLY_READER_ROLE;
```
***
## Cost Optimization
Snowflake charges for compute (warehouse usage). To manage costs:
* Use an **X-Small warehouse** — sufficient for most sync operations
* Set **auto-suspend** to 1 minute to minimize idle time
* Consider a dedicated warehouse for Quivly to track usage separately
```sql theme={null}
CREATE WAREHOUSE IF NOT EXISTS QUIVLY_WH
WAREHOUSE_SIZE = 'X-SMALL'
AUTO_SUSPEND = 60
AUTO_RESUME = TRUE;
GRANT USAGE, OPERATE ON WAREHOUSE QUIVLY_WH TO ROLE QUIVLY_READER_ROLE;
```
***
## Security Notes
* Quivly only requests read-only (SELECT) access
* Credentials are encrypted at rest and in transit
* Revoke access anytime by dropping the user or revoking the role
***
**Need help?**
* Email support: [support@quivly.ai](mailto:support@quivly.ai)
* Book a call: [Schedule onboarding](https://cal.com/chandrika)
# What is Quivly?
Source: https://docs.quivly.ai/introduction
Quivly is an AI-native customer intelligence platform. It connects your CRM, billing, support, calls, Slack, and product usage data into one customer view, then puts AI to work on it — health scores, agents, drafted actions, and a research assistant.
Quivly gives revenue and customer success teams one place to see and act on everything about a customer. Think of it as a shared brain for your customer data: every system you connect feeds it, and every feature — from health scores to AI agents — reads from it.
## What you can do with Quivly
Every customer's revenue, usage, calls, support tickets, contacts, opportunities, and projects in one profile.
Configurable scoring across revenue, usage, engagement, support, and market signals. Spot risk before it becomes churn.
An AI research assistant that answers questions across all your connected data — in the app or in Slack.
Build workflows that run automatically — on new records, schedules, Slack messages, or health score changes — with human review gates where you want them.
AI-drafted next steps land in an inbox. Review, edit, and send emails, Slack messages, or calendar invites without leaving Quivly.
Build widgets yourself or describe what you want and let AI build the dashboard.
## Who uses it
* **Customer success teams** track health, prep for QBRs with AI notebooks, and get drafted actions when an account moves.
* **Revenue operations** connect the data sources, map fields, and configure scoring.
* **Developers** connect Quivly to Claude and other AI tools through the [Quivly MCP server](/developers/mcp-server), push usage events via [API](/integrations/product-usage/api-overview), and import [skills from GitHub](/developers/github-skill-import).
## Where to start
Start with your CRM, then billing, support, calls, and product usage. See [integrations](/integrations/introduction).
A three-step wizard: pick who to score, set score ranges and category weights, and let AI configure risk and growth signals. See [health scores](/health-scores/introduction).
Ask questions with [Ask Quivly](/product/ask-quivly), automate with [agents](/product/agents), and turn health changes into drafted [actions](/product/actions).
## Need help?
Email [support@quivly.ai](mailto:support@quivly.ai) or [book a demo](https://cal.com/chandrika). For SOC 2, access controls, and data handling, see [security and compliance](/security).
# Configuration
Source: https://docs.quivly.ai/market-signals/configuration
Set up market signals tracking for your organization
## Overview
Market signals configuration is managed from **Settings → Signals**, on the **Market Signals** tab. (The Signals settings page has three tabs: **Strategic Signals** — the [signal rules](/product/signal-rules) that turn signals into drafted actions — **Market Signals**, and **Notifications**.)
The Market Signals tab holds both the news feed and jobs configuration.
***
## News Feed
Controls what market intelligence Quivly tracks for your customers.
### Enable/Disable
A master toggle enables or disables all news feed tracking. Disabling pauses tracking but preserves your configuration.
### Customer Scope
Choose which customers get signal tracking: **All Customers** (default) or a specific segment.
### Processing Frequency
How often signals are processed: daily, every 3 days, weekly, bi-weekly, or monthly.
### Organization Context
Six fields provide Quivly with context about your business so it can identify relevant signals:
| Field | Description |
| -------------------------- | -------------------------------------- |
| **Users** | Who uses your product |
| **Buyers** | Decision makers you sell to |
| **Who We Are** | Brief description of your organization |
| **Market Signals** | Key signals relevant to your business |
| **Problem We Solve** | The problem your product addresses |
| **Ideal Customer Profile** | Description of your ideal customers |
Click **Generate with AI** to auto-populate all six fields based on your organization's profile.
### Tracked Keywords
Add keywords and phrases to monitor news and mentions relevant to your customers. Each keyword is configured independently:
* **Keyword/Phrase** - The search term to track
* **Time Range** - How far back to search (day, week, or month)
* **Include Domains** - Specific domains to prioritize (optional)
* **Exclude Domains** - Domains to filter out (optional)
* **Positive Signals** - What makes content relevant (1-2 sentences)
* **Negative Signals** - What content should be excluded (1-2 sentences)
Keywords can be toggled active/inactive without deleting them. Active keywords require the keyword text and both positive and negative signal definitions.
Click **Refine with AI** on any keyword to improve its positive and negative signal definitions.
***
## Jobs
The Jobs section (on the same tab) configures tracking of job postings at customer companies.
### Enable/Disable
A master toggle enables or disables all job tracking.
### Job Keywords
Four keyword fields define what job postings to match:
| Field | Description |
| ------------------------ | ---------------------------------------------------- |
| **Title Keywords** | Keywords to match in job titles |
| **Description Keywords** | Keywords to match in job descriptions |
| **Technology Keywords** | Technology stack keywords to track |
| **Country Codes** | Filter by country (optional, all countries if empty) |
### Relevance Criteria
* **Positive Signals** - What makes a job posting relevant to your business
* **Negative Signals** - What job postings to exclude
Click **Refine with AI** to improve the relevance signal definitions.
At least one keyword field must be filled when jobs tracking is enabled, along with both positive and negative signals.
***
## Saving
Click **Save Configuration** when done. An unsaved changes indicator appears when you have pending modifications.
# Overview
Source: https://docs.quivly.ai/market-signals/introduction
Track external events and market intelligence affecting your customers
## What are Market Signals?
Market signals are external events and intelligence about your customers that Quivly automatically tracks and analyzes. Signals include funding rounds, leadership changes, layoffs, acquisitions, company news, and job postings.
Market signals contribute to customer health scores. Positive signals improve health, negative signals decrease it.
***
## Where Market Signals Appear
### Global Dashboard
The **Market Signals** page in the main navigation shows aggregated signals across all customers, with four tabs:
* **News Feed** - Market intelligence from tracked keywords and news sources
* **Jobs** - Relevant job postings detected at customer companies
* **Competitive Intel** - coming soon
* **Leadership Changes** - coming soon
News Feed and Jobs include search, sentiment filtering, and relevance filtering.
### News Feed View
Each signal card displays:
* **Title and summary** - AI-generated headline and description
* **Sentiment badge** - Positive (green), Negative (red), or Neutral (gray)
* **Customer** - Which customer the signal relates to
* **Relevance** - Level (High/Medium/Low) with a strength indicator and AI-generated explanation
* **Tags** - Categorization labels
* **Source links** - Clickable badges linking to the original articles
* **Timestamp** - When the signal was detected
### Jobs View
Two display modes are available:
* **Job First** - List of jobs with company info per job
* **Company First** - Companies grouped with their matching jobs listed under each
Filter by search, date range, and toggle between views.
### Customer Profile
Each customer's **Market Signals** tab shows signals specific to that customer, with the same search, sentiment, and relevance filters.
***
## Health Score Impact
Market signals are one of five categories in the health score calculation. Scoring is automatic:
* **Positive signals** (funding, hiring growth) improve the score
* **Negative signals** (layoffs, financial trouble) reduce the score
* **Neutral signals** have no impact
The lookback period (30d or 90d) and category weight are configurable in the health score settings.
# Migrating to Quivly
Source: https://docs.quivly.ai/migrations/introduction
How to move from another customer success platform, CRM, or spreadsheet to Quivly. What carries over automatically, what you rebuild, and how to export from common tools.
Migrating to Quivly is not a data dump-and-load. Quivly connects directly to the systems your data already lives in — [Salesforce or HubSpot](/integrations/crm/salesforce), [Stripe](/integrations/billing/stripe), [support](/integrations/support/pylon), [calls](/integrations/call-recordings/fireflies), [Slack](/integrations/communication/slack), and your [warehouse](/integrations/warehouses/overview) — the same sources your old tool was reading from. So most of your data isn't migrated at all; you reconnect the source and it flows in live.
What you *do* migrate is the layer that only existed inside the old tool: your health-score model, playbooks, segments, and any data you kept only there.
## What carries over vs. what you rebuild
| Data | How it gets into Quivly |
| ------------------------------------------ | ------------------------------------------------------------------------------------- |
| Accounts / customers | Sync from your [CRM](/integrations/crm/salesforce) — not exported |
| Contacts | Sync from CRM |
| Opportunities / renewals | Sync from CRM |
| Revenue, subscriptions, invoices | Sync from [Stripe](/integrations/billing/stripe) |
| Support tickets | Sync from [support](/integrations/support/pylon) |
| Call transcripts & summaries | Sync from [call recordings](/integrations/call-recordings/fireflies) |
| Product usage | [Warehouse, PostHog, or Usage Push API](/integrations/warehouses/overview) |
| Health score model | **Rebuild** in [Health Scores](/health-scores/configuration) |
| Playbooks / CTAs / automations | **Rebuild** as [Agents](/product/agents) |
| Segments | **Recreate** as [custom views](/customer-views/custom-views) |
| Success plans, QBR notes, tool-only fields | **Recreate** as [custom objects/fields](/data-models/custom-objects) — backfill below |
| Historical health scores, NPS trends | Not migrated — Quivly recomputes going forward |
Quivly has no bulk CSV importer for core records, and it never writes back to your source systems. Connecting the integration *is* the import. Data that lives only in your old CS tool is handled in [Backfilling tool-only data](#backfilling-tool-only-data).
## The migration playbook
Connect CRM first, then billing, support, calls, Slack, and usage. Each source populates customers and their history automatically. See the [quick start](/quickstart-admin).
Records from different systems link to one customer profile by email domain and external IDs. Confirm they resolved correctly — see [cross-system linking](/field-mappings/cross-system-linking).
Translate your old scorecard into Quivly's weighted categories — revenue, usage, engagement, support, market signals. See [health score configuration](/health-scores/configuration). You can [test it](/health-scores/testing-scores) against real customers before going live.
Rebuild your books of business and risk segments as [custom views](/customer-views/custom-views) with filters and saved columns.
Each playbook or CTA rule becomes an [agent](/product/agents): a trigger (health change, record update, schedule, Slack) plus steps, with a Review gate before anything sends. See the [template agents](/product/agents#template-agents) for common patterns.
Move any data that lived only in the old tool — see below.
## Coming from another CS platform
Your accounts, contacts, renewals, and tickets already live in your CRM, billing, and support tools — connect those and they sync. From the CS platform itself you only need to carry over what was unique to it: the scoring logic, playbooks, and any custom data. Most platforms export the latter via a CSV/report export or their API.
| Coming from | Already flows in via integrations | Export from the old tool | Rebuild in Quivly |
| ------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Gainsight** | Accounts, contacts, opportunities (Salesforce/HubSpot); tickets; usage | Scorecards, CTAs, Success Plans, custom MDA fields | Health model, [agents](/product/agents), [custom objects](/data-models/custom-objects) |
| **ChurnZero** | Accounts, contacts, renewals, tickets, usage | ChurnScores, Plays, Journeys, custom attributes | Health model, agents, custom fields |
| **Totango** | Accounts, contacts, usage | Health, SuccessPlays, SuccessBLOCs, custom attributes | Health model, agents, views |
| **Vitally** | Accounts, contacts, tickets, usage | Health scores, Playbooks, Traits, Docs/notes | Health model, agents, custom objects |
| **Catalyst** | Accounts, contacts, opportunities, usage | Health profiles, Playbooks, custom fields | Health model, agents, custom fields |
| **Planhat** | Accounts, contacts, revenue, tickets, usage | Health, Playbooks, custom data models | Health model, agents, custom objects |
| **Custify** | Accounts, contacts, subscriptions, usage | Health, Playbooks, custom dimensions | Health model, agents, custom fields |
The pattern is the same for any tool: **don't re-export what your CRM/billing already owns** — re-express the scoring and automation logic, and backfill only the truly tool-specific data.
## Coming from a CRM or spreadsheets
If today's "system" is just your CRM (or a spreadsheet feeding one): connect the CRM and you're most of the way there. Fields that lived only in a spreadsheet — renewal notes, onboarding stage, a manual risk flag — become [custom fields](/data-models/custom-fields) on the customer, or a [custom object](/data-models/custom-objects) for repeating records like success plans. Get the values in by writing them to your CRM (so they sync) or via the backfill options below.
## Backfilling tool-only data
For data that isn't in any connected source, in order of preference:
1. **Write it to a connected system.** The cleanest path — add the field/value in your CRM and it syncs into Quivly like everything else, and stays current.
2. **Model it as a custom object or field**, then populate it. Good for success plans, onboarding stages, or account-level flags. See [custom objects](/data-models/custom-objects) and [custom fields](/data-models/custom-fields).
3. **Push usage history** via the [Usage Push API](/integrations/product-usage/api-overview) if you're carrying historical product-usage events.
4. **Ask us.** For a large one-time backfill, email [support@quivly.ai](mailto:support@quivly.ai) — [book time with the team](https://cal.com/chandrika) if you'd like a hand planning the move.
## FAQ
No. They sync from your CRM. Exporting and re-importing them would create duplicates that fight the live sync. Connect the CRM instead.
There's no CSV importer for core records — Quivly builds its customer model from your connected systems. Data that isn't in any source is handled through [backfilling](#backfilling-tool-only-data): write it to your CRM, or model it as a custom object/field.
No — Quivly computes health from your live data using the model you configure, so scores start fresh and build history from your connect date forward. Underlying history (revenue, usage, calls) still syncs, so trends fill in quickly.
Most teams are live in less than a week, mainly gated by initial sync volume and rebuilding the health model and playbooks. See the [implementation FAQ](/faq).
Yes. Quivly's data integrations are read-only, so connecting them changes nothing in your source systems — you can run both in parallel until you're ready to cut over.
# Actions
Source: https://docs.quivly.ai/product/actions
An inbox of AI-drafted recommendations and workflow approvals. Review suggested next steps, edit drafts, and send emails, Slack messages, or calendar invites from one place.
The **Actions** page is your team's to-do inbox for AI output. Two kinds of items land here:
* **Recommendations** — AI-drafted next steps for an account, generated when a [signal rule](/product/signal-rules) fires (a health drop, a negative call, a usage change) or by an [agent](/product/agents).
* **Approvals** — agent runs paused at a Review step, waiting for a human decision.
The inbox has two lanes — **Strategic** (account-level recommendations) and **Operational** (approvals and system tasks) — with filters for status, a "My Accounts" toggle, and search.
## Working a recommendation
Each recommendation shows the customer, a Risk / Growth / Neutral chip, what changed (health bucket movement with per-category deltas) or what was noticed (the signals that fired), and a list of suggested next steps.
Steps are either:
* **Manual** — tick the checkbox when you've done it, or
* **Tool steps** — click **Review** to open the Execute modal, where the AI's draft is ready to edit and send.
The Execute modal adapts to the tool: an email composer (To/Cc/Bcc, subject, rich-text body, contact picker), a Slack message composer, a support ticket form, or a calendar event with attendees pulled from the customer's contacts. You choose the sender identity — the Quivly bot, your own account, or the account owner. Sending as yourself requires your own [Gmail](/integrations/communication/gmail) or Slack connection.
When you're done: **Mark complete**, or **Dismiss** with a quiet window (1 week to never) so the same recommendation doesn't come right back. Thumbs up/down feedback tunes future recommendations.
## Deciding an approval
Approvals show the workflow context, a snapshot of the data the agent saw, and the proposed change — which you can edit inline before approving. **Approve** resumes the workflow (with your edits); **Reject** sends it down the reject branch. Stacked approvals of the same kind can be decided in bulk. Every decision records who decided, when, and any note.
## FAQ
From [signal rules](/product/signal-rules) you configure (Settings → Signals) and from agents. Nothing appears in the inbox unless a rule or agent you set up generated it.
No. Tool steps in a recommendation only execute when you review and send them. Agents can act autonomously only if you built them without a Review gate.
Yes — every field in the Execute modal is editable, and approvals support approve-with-edits.
# Agents
Source: https://docs.quivly.ai/product/agents
Build automated workflows on a visual canvas — triggered by record changes, schedules, Slack messages, or health score changes — with AI steps, branching, and human review gates.
Agents are automated workflows. Each agent has a trigger, a series of steps on a visual canvas, and a run history. Think of an agent as a playbook that runs itself: "when a customer's health drops, gather context, draft an outreach, and ask me to approve it."
## Creating an agent
From the **Agents** page you can build manually or describe what you want in plain language — for example, *"When an opportunity closes won, create an onboarding project and notify the CSM on Slack."* The AI builder picks the trigger, selects tools, drafts instructions, and wires the canvas. It may ask one clarifying question, and it warns you if a similar agent already exists.
You land on the canvas with an AI chat panel open — keep describing changes and accept or reject each proposed edit.
## Triggers
| Trigger | Fires when |
| -------------- | ------------------------------------------------------------------------------- |
| Record Created | A new record is created in the selected object (with optional field conditions) |
| Record Updated | An existing record changes |
| Schedule | On a cadence (daily, weekly, quarterly, or every N days) for a customer segment |
| Slack Message | A message is posted in a mapped customer channel |
| Health Score | A customer's health bucket changes (optionally to a specific bucket) |
Record triggers support filter conditions (equals, contains, greater than, is empty, and so on) and enrollment control — run once per record, or re-enroll every time.
## Steps
Steps come from a searchable palette, grouped into:
* **AI** — run a [skill](/product/skills) with structured input and output.
* **Decision** — If/Else branching, Switch routing by field value, and **Review**: pause until a human approves (approvals show up in [Actions](/product/actions)).
* **Actions** — send a Slack message or DM, create an [AI notebook](/product/notebooks), create or update projects, tasks, and milestones, create/update/delete records, send a webhook, or run an **App Action** in a connected app like Gmail or Google Calendar.
* **Lookups** — read customer data (health scores, calls, revenue, usage, contacts, tickets, and more) to feed later steps.
For user-scoped apps (Gmail, Calendly), you choose who the action sends as: the record's CSM owner, a specific teammate, or whoever published the agent.
Deleting records requires a Review gate.
## Template agents
The trigger, step, lookup, and action primitives combine into playbooks for most customer-facing workflows. These five are the ones teams reach for first — each is buildable today from the palette above, either by hand or by describing it to the AI builder.
| Agent | How it's built | What it does |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Churn save play** | Health Score trigger (bucket drops) → Lookups (health, calls, usage) → AI [skill](/product/skills) to draft outreach → Review → Slack DM to the CSM | Catches a health decline the moment it happens, packages the context, and puts a ready-to-send message in front of the owner for approval. See [Identifying at-risk customers](/workflows/identifying-at-risk-customers). |
| **Onboarding kickoff** | Record Updated (opportunity → Closed Won) → create onboarding project with tasks and milestones → notify the CSM on Slack → App Action to send a welcome email | Turns a won deal into a fully scaffolded onboarding plan and a first-touch email, with no manual setup. |
| **Renewal prep brief** | Schedule (N days before renewal) → Lookups (revenue, contracts, usage, health) → AI [notebook](/product/notebooks) for a renewal brief → Review → assign a prep task | Gives the owner a data-backed renewal brief on a predictable cadence, ahead of every renewal date. |
| **Slack signal triage** | Slack Message trigger (mapped customer channel) → AI skill to classify and summarize → If/Else branch → create an [Action](/product/actions) and DM the owner on risk, or log a note otherwise | Reads every customer channel message, routes the urgent ones to a human, and quietly files the rest. |
| **Expansion spotter** | Schedule or Record Updated (usage crosses a threshold) → Lookups (usage, contacts) → AI skill to spot the opportunity → Review → draft outreach via App Action | Surfaces accounts ready to grow and drafts the expansion outreach for review. |
**Use cases these unlock:** churn prevention and account saves, hands-off onboarding, renewal and QBR prep, revenue expansion, support escalation, and scheduled executive or segment reporting — anywhere a repeatable "when X happens, gather context and act" playbook applies.
## Publishing and runs
Agents are drafts until you publish; each publish creates a version. You can test-run from the builder before going live, and pause an agent by toggling its status.
**Run History** shows every run with its status (Pending, Running, Awaiting Review, Completed, No Action Taken, Failed, Cancelled), version, whether it fired automatically or manually, and a full step-by-step trace. Running or paused runs can be cancelled.
## FAQ
Only if you build it that way. Add a Review step before any outbound action and the run pauses until someone approves it in the Actions inbox.
Each customer in the segment runs once per cadence window — a daily agent won't run twice for the same customer in a day.
No. Agents are built on a visual canvas, and the AI builder can assemble one from a plain-language description.
# AI Fields
Source: https://docs.quivly.ai/product/ai-fields
Customer fields computed by AI from each customer's data — on a schedule or on demand — with testing, versioning, and segment targeting.
AI fields are custom fields whose values the AI computes from each customer's data. Instead of a CSM writing an "account summary" or judging "expansion readiness" by hand, the field fills itself in — for every customer, on a schedule.
Create one from any customer field list: **Add field → AI-powered**. AI fields are currently available on customers.
## Configuring
The editor has four tabs — **Setup, Test, Runs, Versions**:
* **Setup** — write the instructions yourself, copy them from a [skill](/product/skills), or describe your intent and let AI generate the prompt. Pick the tools the field may read, and optionally limit the audience to a segment (with a live count of matched customers).
* **Test** — run the draft on one customer and watch the AI's steps, then see the value, its reasoning, and the tools used. A batch test dry-runs up to 50 customers with no writes.
* **Runs** — history of computations, plus **Run all** to recompute every targeted customer on demand.
* **Versions** — every publish saves a snapshot.
Output types: Markdown (default), text, number, yes/no, single select, or JSON. The type is fixed at creation.
## Refresh schedule
Daily, weekly (Mondays), every 15 days, monthly, or **manual only**. Scheduled runs fire at 9:00 AM in the field's timezone.
## FAQ
AI fields are their own fields, computed by AI — they don't write into your standard or synced fields.
Non-empty instructions and at least one tool. Until you publish, the field only runs in tests.
Yes — test runs show the value alongside the AI's reasoning and which tools it read.
# Ask Quivly
Source: https://docs.quivly.ai/product/ask-quivly
An AI research assistant that answers questions across your connected customer data — customers, revenue, health scores, tickets, calls, conversations, and the web.
Ask Quivly is a chat assistant that works across your whole organization's data. Ask a question in plain language and it searches your customers, contacts, opportunities, support tickets, calls, notes, Slack conversations, revenue, usage, billing, contracts, health scores, market insights, notebooks, and projects — plus the public web — to answer.
It's like asking a colleague who has every dashboard memorized.
## Using it
Open **Ask** in the sidebar, type your question, and press Enter. Starter prompts help you begin:
* "Which customers have a critical or high risk health score right now?"
* "What does our MRR look like by customer segment?"
* "Show me all open support tickets by priority"
* "What were the key takeaways from our most recent customer calls?"
Chats are saved as sessions per user, with a history sidebar and an archive.
## Options
* **Skills** — type `/` or open the Skills menu to run a saved [skill](/product/skills); its instructions steer the whole session.
* **Web search** — on by default; answers that use the web show their sources as citations you can open.
* **Tools** — you can turn individual data tools off for a chat.
Every answer carries the reminder: *"AI-powered answers from your connected data. Verify before acting."*
## Limits
* 10 AI requests per minute per user.
* Conversations cap at 100 messages — start a new chat after that.
* A guard rail rejects off-topic or unsafe prompts.
## FAQ
No. Ask Quivly is read-only. To act on something (send a message, update a record), use [agents](/product/agents) or [actions](/product/actions). See [security and compliance](/security).
No — it works across your entire organization. For content about a single customer, use [notebooks](/product/notebooks) on that customer's page.
Yes. The same assistant answers in Slack via DM or @mention. See [Ask Quivly in Slack](/product/ask-quivly-slack).
# Ask Quivly in Slack
Source: https://docs.quivly.ai/product/ask-quivly-slack
Use the Quivly Slack bot to ask about customers, health scores, revenue, tickets, and calls — by DM, @mention, or thread reply.
Once your workspace has the [Slack integration](/integrations/communication/slack) connected, the same assistant behind [Ask Quivly](/product/ask-quivly) is available inside Slack.
## Ways to use it
* **DM the bot** — message Quivly directly and ask anything about your customers. Suggested prompts cover portfolio health, revenue, at-risk accounts, and support load.
* **@mention in a channel** — `@Quivly which accounts renewed this month?` runs the question in the channel.
* **Summarize a thread** — @mention the bot inside a thread with no question and it summarizes the thread and suggests next steps.
* **Reply in a thread** — once the bot has answered in a thread, follow-ups don't need an @mention.
* **App Home** — the bot's Home tab shows a portfolio summary: total customers, MRR, at-risk counts, and the top accounts needing attention.
## What answers look like
The bot replies with formatted Slack messages — headers, tables, and charts uploaded as images. While it works, it posts live progress updates and reacts with 👀, switching to ✅ when done. Answers can include follow-up action buttons and 👍/👎 feedback buttons.
It can also read image attachments you include with a question.
## Limits
* 10 requests per minute per Slack user.
* Thread context uses up to the last 40 messages.
## FAQ
The bot answers where it's invited — DMs, @mentions, and threads it's part of. Separately, channels you've mapped to customers are ingested for conversation intelligence; see the [Slack integration](/integrations/communication/slack).
An admin needs to install the Quivly Slack app under **Settings → Integrations → Slack**.
# Product FAQ
Source: https://docs.quivly.ai/product/faq
Common questions about using Quivly day to day — health scores, Ask Quivly, agents, actions, notebooks, and dashboards.
Scores need a published config (**Settings → Health Score**) and calculate on a daily run after publishing. Categories only contribute if their data source is connected.
Yes — one all-customers config plus one config per segment, each with its own weights, thresholds, and signals. See [configuration](/health-scores/configuration).
[Ask Quivly](/product/ask-quivly) answers questions when you ask. [Agents](/product/agents) run workflows automatically on triggers. [Actions](/product/actions) is the inbox where AI-drafted recommendations and workflow approvals wait for a human.
Recommendation drafts always wait for a person to review and send. Agents can send autonomously only if you built and published a workflow without a Review gate — adding one pauses the run for approval. See [security and compliance](/security).
A [skill](/product/skills) is saved instructions plus a data-tool allowlist. Create one when you want a repeatable output — QBR prep, renewal risk reads — instead of retyping the same prompt.
Ask Quivly gives chat answers across the whole org. A [notebook](/product/notebooks) is a persistent document on one customer's page — editable, formatted, and reusable for things like QBRs and handoffs.
Yes — open a dashboard's AI panel and describe what you want; it adds widgets (metric tiles, bar, line, pie, and table) one by one. See [dashboards](/dashboards/creating-dashboards).
Completed and dismissed items leave the open view (use the status filter to see them). Dismissing with a quiet window also keeps the rule from re-firing for that account during the window.
# News Feed
Source: https://docs.quivly.ai/product/insights
A feed of market intelligence and keyword-tracked insights about your customers from external sources, with sentiment and relevance filters.
The News Feed (under **Market Signals**) collects externally sourced intelligence about your customers — news, announcements, and keyword-tracked mentions — as a scrollable feed, newest first.
Each card shows the insight's title, summary, sentiment, relevance, tags, and the customer it's about.
## Filtering
* **Search** — free text across titles, summaries, customers, and tags.
* **Sentiment** — positive, negative, or neutral.
* **Relevance** — relevant/irrelevant, or by level (high, medium, low).
The feed shows a result count and when insights were last processed.
Insights are generated automatically once [market signals are configured](/market-signals/configuration) — there's nothing to run manually. High-relevance insights also feed each customer's [health score](/health-scores/introduction) and can fire [signal rules](/product/signal-rules).
## FAQ
From external sources monitored using your market signals configuration — the companies, keywords, and topics you've set up.
Insights appear after market signals are configured and the first processing run completes. Check [market signals configuration](/market-signals/configuration).
# AI Notebooks
Source: https://docs.quivly.ai/product/notebooks
Customer documents written by AI from live data — QBR prep, handoffs, renewal briefs — in a rich-text editor with accept/discard review.
Notebooks are documents that live on a customer's page. The AI writes them from that customer's actual data — calls, revenue, tickets, usage, health — so a QBR brief or sales handoff takes seconds instead of an afternoon of tab-hopping.
Each notebook belongs to one customer. The layout: notebook list on the left, the document in the center, and an auto-built table of contents on the right. Edits autosave.
## Writing with AI
Two ways in:
* **Slash command** — type `/` anywhere in the editor, write a prompt (or pick a [skill](/product/skills)), and the AI inserts content at your cursor.
* **Write with AI** — on an empty notebook, run a saved skill, a free-form prompt, or both (your prompt layers on the skill as extra focus). This fills the whole notebook.
AI text streams in highlighted. When it finishes, choose **Accept**, **Discard**, or **Retry**. Accepted content gets a **Sources** line listing the data platforms the AI actually read — derived from its real lookups, not guessed.
The rest is a normal rich-text editor: headings, lists, tables, and manual editing anywhere.
## Limits
* Prompts up to 5,000 characters.
* Generation runs up to \~2.5 minutes before timing out.
## FAQ
No — each notebook is scoped to its customer, enforced server-side.
Yes. An [agent](/product/agents) can create a notebook as a workflow step, and the [Quivly MCP server](/developers/mcp-server) exposes `create_notebook` so external AI tools like Claude can generate one.
From the notebook's settings panel — deletion asks you to type the notebook's title to confirm.
# Opportunities
Source: https://docs.quivly.ai/product/opportunities
Your deal pipeline from the CRM, viewable as a board, calendar, or list — org-wide and per customer — with saved views.
Opportunities are your deals, synced from [Salesforce](/integrations/crm/salesforce) or [HubSpot](/integrations/crm/hubspot). Quivly shows them next to everything else you know about the customer — health, usage, support load — instead of in a separate CRM tab.
## Views
The **Opportunities** page offers three layouts:
* **Board** — deals as cards grouped in columns.
* **List** — a filterable, sortable table.
* **Calendar** — deals laid out by date.
You can filter and sort, then save the setup as a named view to return to (or share). Views save explicitly — adjust, then save. Frequently used views can be pinned.
Each customer's page also has an **Opportunities** tab showing just that account's deals, and open pipeline feeds the customer's revenue picture and [health score](/health-scores/introduction) context.
## FAQ
Deal data comes from your CRM — the CRM stays the system of record. Use [Ask Quivly](/product/ask-quivly) or [agents](/product/agents) to analyze and act on pipeline.
Opportunities update as your CRM integration syncs. Check the integration's detail page for sync activity.
# Projects
Source: https://docs.quivly.ai/product/projects
Customer-scoped project management — onboarding plans, implementations, and success plans with tasks, milestones, templates, and updates.
Projects track structured work with a customer: onboarding, implementation, migration, a success plan. Each project belongs to a customer and holds tasks and milestones, so delivery status lives on the same profile as health and revenue.
## Working with projects
* **Per customer** — the customer's **Projects** tab lists their projects; inside one you manage tasks, milestones, and post **updates**.
* **Org-wide** — the **Projects** page shows projects across all customers, with filters and saved views like the customer list.
* **Templates** — define reusable project templates under **Settings → Projects → Templates** so every onboarding starts from the same plan. Agents can create projects from a template automatically.
Projects have statuses (not started, in progress, completed, cancelled) and target dates; overdue projects and milestones are tracked per customer and can feed dashboards.
## Automation
[Agents](/product/agents) can create and update projects, tasks, and milestones as workflow steps — for example, spinning up an onboarding project from a template the moment a deal closes won.
## FAQ
Projects in Quivly are customer-scoped — they're a delivery record on the account, not a general project tool.
Milestones are the headline checkpoints of a project; tasks are the work items. Both have statuses and due dates.
# Signal Rules
Source: https://docs.quivly.ai/product/signal-rules
Turn customer signals — health drops, negative calls, usage changes, renewals — into AI-drafted recommendations, per segment, with a sensitivity dial and dry-run testing.
Signal rules decide *when* Quivly drafts a [recommendation](/product/actions) for an account. You configure them under **Settings → Signals**.
A rule is like a tripwire per segment: when a chosen signal fires for a customer, the AI drafts next steps and drops them in the Actions inbox.
## Setting up a rule
The editor walks through four steps:
Target all customers or a specific segment.
Pick which signals fire the rule: health bucket changes, score drops or rises, negative calls, negative Slack conversations, approaching renewals, usage drops or surges, negative market news, hiring signals, or a semantic "something was said" trigger. Each trigger is an editable plain-English sentence with a Risk / Growth / Neutral polarity.
Choose which connected integrations the AI may draft actions through, who suggested actions run as (the CSM owner or the acting user), and optional freeform guidance for the AI.
Optionally notify Slack — DM the account owner or post to a channel, with a fallback channel.
A **sensitivity dial** (Conservative / Balanced / Aggressive / Custom) sets thresholds and cadence in one move, and a quiet-period setting ("stay quiet after handling for N days") stops repeat firing on the same account.
## Testing and publishing
Rules are drafts until published; each publish creates a version. The **Test** tab runs a dry-run preview: how many customers would fire right now, with a sample list and which triggers matched. Semantic triggers aren't evaluated in dry-run.
You can pause action generation, rename, or archive a rule from its settings panel.
## FAQ
Signal rules only produce drafted recommendations for humans to review. [Agents](/product/agents) run multi-step workflows that can act on their own (with optional review gates).
The sensitivity dial and quiet period control that — after a recommendation is handled, the rule stays quiet for that account for the window you set (1–90 days).
# Skills
Source: https://docs.quivly.ai/product/skills
Reusable AI instructions — a prompt plus a set of data tools — that steer Ask Quivly, notebooks, and AI fields. Create from scratch, from templates, or with AI.
A skill is a saved recipe for the AI: **instructions** (what to produce and how) plus a **tool allowlist** (which data it may read). Write it once, and your whole team gets the same QBR prep, renewal risk read, or health digest every time.
Manage skills under **Settings → AI → Skills**.
## Creating a skill
Three paths: start from scratch, pick a **template** (eight built-in, covering post-sale, renewals, onboarding, health, and reporting — e.g. Sales Handoff Brief, QBR Prep, Churn Risk Assessment), or let AI generate one from a description.
The editor includes an AI chat assistant that can draft the skill from your intent, edit instructions, suggest improvements, and browse or restore versions. Skills can read from \~20 data tools — customer profiles, contacts, calls, health scores, revenue, usage, insights, aggregations, and more.
Developers can also [import skills from GitHub](/developers/github-skill-import) in the Anthropic Agent Skills format.
## Lifecycle
* **Draft → Publish** — publishing makes the skill active and saves an immutable version snapshot. Version history shows diffs and supports restore.
* Each active skill gets a slash command name, so you can invoke it as `/skill-name` in Ask Quivly.
* **Duplicate** forks a skill; **Archive** retires it.
Publishing requires instructions and at least one tool. Names are 1–2 words; instructions up to 10,000 characters.
## Where skills run
| Surface | How |
| --------------------------------- | ---------------------------------------------------------------- |
| [Ask Quivly](/product/ask-quivly) | `/` slash command or the Skills menu |
| [Notebooks](/product/notebooks) | Write with AI and the editor slash command |
| [AI fields](/product/ai-fields) | "Use a skill" copies its instructions and tools into the field |
| [Agents](/product/agents) | The Skill step runs one inside a workflow |
| [MCP](/developers/mcp-server) | External AI tools list skills and use them to generate notebooks |
## FAQ
No — skill tools are read-only. Write operations happen through agent action steps, not skills.
Editing continues on a draft; the published version keeps running until you publish again. To fork a different direction, use Duplicate.
# Quick Start for Admins & RevOps
Source: https://docs.quivly.ai/quickstart-admin
Set up Quivly for your organization: connect your CRM and billing, map fields, invite your team, configure health scores, and turn on Slack notifications.
This guide is for **administrators and revenue operations** setting up Quivly for their organization. If you need onboarding help, [book time with the team](https://cal.com/chandrika).
## Step 1: Connect your CRM
Your CRM brings in the core customer list that everything else links to.
Go to **Settings → Integrations**, click **Salesforce** or **HubSpot**, and open the **Configure** tab.
Complete the embedded connection flow — sign in to your CRM and approve read access. Quivly syncs customers, contacts, opportunities, and owners (plus contracts from Salesforce and meetings from HubSpot).
Syncing is continuous — changes flow in via webhooks rather than on a fixed schedule. Check the integration's **Logs** tab for activity.
## Step 2: Invite your team
Go to **Settings → Members**, click **Invite Member**, enter an email, and pick a role (roles come from your organization's setup — typically Admin and Member; only Admins can change settings and integrations). Invitations expire after 7 days and can be revoked. You can also deactivate and reactivate members later.
## Step 3: Review field mappings
Go to **Settings → Objects → Customers → Configuration**. Pick your integration and the object type (e.g. HubSpot Companies).
Default mappings cover the common fields. To track a CRM custom field, map it to an existing Quivly field or create a new custom field inline. See [field mappings](/field-mappings/introduction).
Click **Save Mappings**. Mapping changes apply to future syncs.
Once saved, an object's integration source is locked — contact support to change it.
## Step 4: Connect billing
Connect **Stripe** the same way as your CRM (Settings → Integrations → Stripe → Configure). Quivly syncs billing customers, subscriptions, invoices, and products — powering MRR, renewal dates, and revenue-based health scoring. Stripe records match to your CRM customers automatically; see [cross-system linking](/field-mappings/cross-system-linking).
## Step 5: Configure health scores
Go to **Settings → Health Score** and create a config. The wizard has three steps.
Score **all customers**, or a specific **segment** (you can add one config per segment later with different weights and thresholds).
Drag the boundaries between the four score buckets (Critical, At Risk, Medium, Healthy), then enable the categories that matter — revenue, product usage, engagement, support, market signals — and set their weights. Weights must total 100%. Categories with no connected integration are marked so you know what data is missing.
Click **Auto-configure** — AI generates risk and growth signals tailored to your organization and connected tools. Edit them as plain text.
Test the config on a specific customer, then **Publish**. Scores calculate on the next daily run, and every publish is saved to version history.
## Step 6: Turn on Slack notifications
1. Install the Quivly Slack app under **Settings → Integrations → Slack** (this also enables the [Ask Quivly bot](/product/ask-quivly-slack) and conversation tracking for mapped channels).
2. Go to **Settings → Signals → Notifications**: pick a channel, choose which insight relevance levels to send (all, high, medium, or low), and set the delivery schedule (immediate, hourly, daily, or weekly).
## Step 7: Verify
* **Settings → Integrations** shows each integration's status: **Healthy**, **Unhealthy**, **Not Connected**, or **Not Set Up**. Open a data-source integration's **Logs** tab to inspect sync activity.
* Open **Customers** and spot-check a few profiles: fields mapped correctly, revenue present, contacts linked.
## Where to next
Support, call recordings, and product usage make scores and AI answers richer.
Ask Quivly, agents, actions, and notebooks all run on the data you just connected.
## FAQ
The initial sync depends on data volume; after that, changes stream in continuously via webhooks. Check the integration's Logs tab if something looks stale.
Open the integration and review its logs — most issues are authentication-related and fixed by reconnecting.
Yes — mappings are editable anytime and apply to future syncs. The integration source for an object, however, is locked after first save (contact support to change it).
# Security and Compliance
Source: https://docs.quivly.ai/security
Quivly is SOC 2 Type II compliant and applies security, privacy, and access controls to protect customer data.
## Compliance
| Framework | Status |
| ------------- | ----------- |
| SOC 2 Type II | Compliant |
| ISO 27001 | In progress |
| GDPR | In progress |
| HIPAA | In progress |
The [Quivly Trust Center](https://trust.mycroft.io/quivly) has the latest compliance status, SOC 2 Type II report, security policies, controls, and subprocessors.
Contact Quivly at [privacy@quivly.ai](mailto:privacy@quivly.ai) before processing protected health information or other specially regulated data.
## How Quivly protects your data
Quivly's security program covers encryption, vulnerability management, network boundaries, segregated environments, secure software development, vendor risk management, incident response, business continuity, and disaster recovery. The [Trust Center](https://trust.mycroft.io/quivly) lists the current policies and controls.
Customer data is scoped to your Quivly organization. The app, [Slack bot](/product/ask-quivly-slack), [Ask Quivly](/product/ask-quivly), and [MCP server](/developers/mcp-server) only return data from the signed-in user's organization.
[Admins](/settings/organization-settings) manage integrations, settings, and team access. Deactivating a member removes access immediately.
## Connected systems and AI actions
[Data-source integrations](/integrations/introduction) are read-only. Quivly never writes back to your CRM, billing, support, or warehouse systems on its own.
Outbound actions — such as sending an [email](/integrations/communication/gmail), posting a [Slack](/integrations/communication/slack) message, or creating a [calendar](/integrations/communication/google-calendar) event — only happen through [workflows](/product/agents) your team configures.
[Agents](/product/agents) support Review steps that pause a workflow for human approval. Recommendations generated by [signal rules](/product/signal-rules) are always drafts in [Actions](/product/actions).
[AI-generated answers](/product/ask-quivly) should be verified before they're used for customer or revenue decisions.
## Privacy
The [Quivly Privacy Policy](https://www.quivly.ai/privacy-policy) explains how personal information is collected, used, transferred, and disclosed.
Current subprocessors and security documents are available through the [Trust Center](https://trust.mycroft.io/quivly).
For security or privacy questions, contact [privacy@quivly.ai](mailto:privacy@quivly.ai).
# Notifications
Source: https://docs.quivly.ai/settings/notifications
Configure Slack notifications for market signals
## Overview
Receive market signal notifications in Slack when important events happen with your customers—funding rounds, leadership changes, acquisitions, and more.
***
## Setup
1. Go to **Settings** → **Signals** → **Notifications**
2. Click **Connect Slack**
3. Authorize Quivly in your Slack workspace
Choose which Slack channel should receive notifications. The Quivly bot will automatically join the channel.
Set your notification preferences (see below)
***
## Notification Preferences
### Insight Level
Choose which market signals to receive:
| Level | What you'll get |
| ---------- | ---------------------------------------- |
| **All** | Every market signal detected |
| **High** | Only high-importance signals |
| **Medium** | Medium and high-importance signals |
| **Low** | Low, medium, and high-importance signals |
### Delivery Schedule
Choose when to receive notifications:
| Schedule | Description |
| ------------- | ---------------------------------------- |
| **Immediate** | As soon as signals are detected |
| **Hourly** | Bundled summary every hour |
| **Daily** | Daily digest at a specific time |
| **Weekly** | Weekly digest on a specific day and time |
For Daily and Weekly schedules, select your preferred time and timezone.
***
## Test Notifications
Click **Test Notification** to verify your Slack setup is working correctly. Save requires a channel, insight level, and schedule to all be set.
***
## Disconnect Slack
To stop receiving notifications, click **Disconnect** in the Slack section.
# Team Members
Source: https://docs.quivly.ai/settings/organization-settings
Manage team member access and roles
## Overview
Add team members to your Quivly organization and assign them Admin or Member roles.
***
## Roles
| Role | Capabilities |
| ---------- | ------------------------------------------------------------------------ |
| **Admin** | Full access: manage integrations, configure settings, add/remove members |
| **Member** | Standard access: view customers, use dashboards, no settings access |
***
## Managing Team Members
### Invite a New Member
Navigate to **Settings** → **Members**
Click **Invite Member** and enter their email address
Choose **Admin** or **Member**
Click **Send**. The invitation expires in 7 days.
### Change a Member's Role
1. Find the member in the list
2. Click the role dropdown
3. Select the new role
### Deactivate a Member
1. Click **Deactivate** next to the member
2. Confirm the action
3. The member loses access immediately
### Reactivate a Member
1. Find the deactivated member
2. Click **Reactivate**
3. Access is restored
### Revoke a Pending Invitation
1. Find the pending invitation
2. Click **Revoke**
# Customer Information Not Linking
Source: https://docs.quivly.ai/troubleshooting/customer-information-not-linking
Why synced data — call recordings, billing, support, and more — sometimes doesn't appear on a customer, and how to fix it
## The symptom
A customer looks emptier than it should:
* The **Calls** tab says "No calls yet" even though you know calls have happened.
* **Revenue** shows no Stripe subscriptions or invoices even though the customer is paying.
* Contacts, support tickets, or usage data are missing.
In the large majority of cases, the cause is the same: **the customer has no domain set.**
A missing domain is the single most common reason synced data doesn't appear on a customer. Check this **first** before digging into the integration itself.
***
## Why the domain matters
Quivly doesn't get a tidy "customer ID" from every integration. Many sources — call recorders, billing, support — only tell us **who was involved**: a list of email addresses. To attach that data to the right customer, Quivly matches the **email domain** against the domains on your customers.
```
alex@acme.com ──▶ domain "acme.com" ──▶ Customer where customer_domain = acme.com
```
No domain on the customer → nothing to match against → the call (or subscription, or ticket) stays unlinked and never shows up on the profile.
***
## The fix: add a domain
Go to the customer's profile in Quivly. If the domain is missing, you'll see an amber **"Domain missing"** badge next to the customer name at the top.
Click the badge and enter the customer's primary domain — e.g. `acme.com`. You can also set it in the **Account Info** panel (the building icon in the top-right of the customer header).
Use the bare domain: lowercase, no `https://`, no `www.`, no trailing path.
New data links automatically. Existing records link on the next sync.
***
## Domain mismatch: the customer has a domain, but data still doesn't link
Sometimes the customer *does* have a domain, yet data still doesn't attach. This is almost always a **domain mismatch** — the people involved email from a domain that isn't the one set on the customer.
Common causes:
* The customer uses **more than one domain** — a parent company, an acquired brand, or a regional domain like `acme.co.uk`.
* The primary domain is set to one thing (`acme.com`) but the data comes in under another (`acme.io`).
**Fix: add the other domains as secondary domains.** Data from *any* listed domain — primary or secondary — links to the customer.
On the customer, open the **Account Info** panel (the building icon at the top-right of the customer header).
Under **Secondary Domains**, add each additional domain the customer uses. Use the bare domain (`acme.io`), one per entry — the same format as the primary domain.
Existing records re-match on the next sync; new data matches immediately.
Not sure which domains to add? Open the customer's **Contacts** tab — the email domains you see there are the ones that should be listed as the primary or a secondary domain.
***
## Where domains normally come from
Ideally you never set domains by hand — they flow in from your CRM.
| Source | Field that becomes the domain |
| ---------- | ------------------------------------ |
| Salesforce | Account **Website** |
| HubSpot | Company **Domain** |
| Manual | The **Domain** field in Account Info |
If domains are consistently missing after a sync, the upstream CRM record is usually missing its website/domain field. Fixing it there means every future customer comes in linked correctly, with no manual step.
***
## By data type
The domain drives linking, but each integration has a small nuance worth knowing.
### Call recordings
Call recorders (Fireflies, Fathom, Granola) link a call by the **email domains of the external attendees**.
* A call attended only by your own team — no external `@customer.com` participant — has nothing to match on and won't link.
* Attendees on **personal email** (`@gmail.com`, `@outlook.com`) won't match a customer domain.
* If a call was attended from a domain the customer uses but that isn't listed, add it as a **secondary domain** (see the mismatch section above).
### Billing information
Stripe subscriptions and invoices link by the **Stripe customer's email domain**.
* If the Stripe customer has **no email**, there's no domain to match — the subscription can't link automatically. Add the email in Stripe, or link the customer manually.
* If billing comes in under a different domain than the CRM record (common when finance uses a `billing@` alias on another domain), add that domain as a **secondary domain**.
### Support tickets
Support tickets (Pylon) link by the **account's domain**.
* A ticket from a domainless account can't match — set the domain on the customer.
* Tickets opened from a secondary or regional domain link once that domain is added as a **secondary domain**.
***
## Still not linking after adding a domain?
If data still doesn't appear once a correct domain is set:
* **Give it a sync cycle.** Existing records link on the next scheduled sync, not instantly.
* **Check the source domain.** The email domain on the call, invoice, or ticket must match the customer's primary or a secondary domain exactly — `acme.io` won't match `acme.com`.
* **Confirm the integration is connected** and syncing under **Settings → Integrations**.
If you've confirmed all of the above and data is still missing, reach out to Quivly support with the customer name and an example call or invoice that should have linked.
# Customer 360 Review
Source: https://docs.quivly.ai/workflows/customer-360-review
Run an account review or QBR from the customer overview, supporting tabs, and an AI notebook written from live data.
## Overview
A customer 360 in Quivly is the profile itself: one account, with health, revenue, usage, calls, support, market signals, opportunities, and projects on the same page. You do not export a separate briefing pack unless you want one — [notebooks](/product/notebooks) write that document from the same data.
Use this workflow to:
* Set the [Overview tab](/customer-views/account-tab) layout your team uses for every review
* Walk the tabs in a fixed order so you do not miss a source
* Generate a QBR, EBR, or handoff notebook and accept or edit the draft
* Ask follow-up questions in [Ask Quivly](/product/ask-quivly) without leaving the account
***
## What you need connected
The review is only as complete as the integrations behind it. Each missing source blanks a section, not the whole profile.
| Tab / object | Typical source |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Overview, contacts, opportunities | [Salesforce](/integrations/crm/salesforce) or [HubSpot](/integrations/crm/hubspot) |
| Revenue | [Stripe](/integrations/billing/stripe) |
| Usage | [Warehouse](/integrations/warehouses/overview), [PostHog](/integrations/product-usage/posthog), or [Push API](/integrations/product-usage/api-overview) |
| Calls | [Fireflies](/integrations/call-recordings/fireflies), [Fathom](/integrations/call-recordings/fathom), or [Granola](/integrations/call-recordings/granola) |
| Support | [Pylon](/integrations/support/pylon) |
| Slack | [Slack](/integrations/communication/slack) |
| Health | A published [health score config](/health-scores/configuration) |
| Market signals | [Market signals](/market-signals/introduction) enabled for the org |
***
## Customize the Overview tab once
The Overview tab is the default view when you open a customer. The layout is shared across customers.
Click **Customers**, then a row. You land on **Overview**.
The header shows name, domain, and LinkedIn, plus quick-edit fields (defaults: **Segment**, **Service Tier**, **Lifecycle Stage**). Use the header customize control to show up to 8 fields. CRM-synced, AI-computed, and read-only fields render as locked pills.
The picker (7d / 30d / 90d / MTD / QTD / YTD / custom / all) scopes every metric section on the canvas. Use **90d** or **QTD** for a quarterly review.
Click **Customize**: drag to reorder, hide sections you do not use, and use each section's gear to pick metrics. Click **Done**. Sections available:
| Section | Contents |
| ------------------ | --------------------------------------------------------------- |
| **Health Score** | Current score, trend, risk badge, history chart (pinned at top) |
| **AI Insights** | AI-written account summary |
| **Revenue** | MRR, ARR, outstanding, days to renewal (warning at ≤30 days) |
| **Usage** | The usage metrics you select, each with value and trend |
| **Support** | Total and open tickets, average resolution and first response |
| **Calls** | Total calls, average duration, average gap, last call |
| **Market Signals** | Three most recent signals with sentiment |
| **Projects** | Active project status |
The collapsible **Account Info** sidebar holds the editable record (owner, domain, custom fields) and read-only CRM / AI fields. Search filters the field list.
***
## Walk the profile
After the overview, open the tabs that still have questions. Stay on one customer until the notebook is done.
| Order | Tab | What to confirm |
| ----- | ---------------------------------------------------- | ----------------------------------------------------------------------------------- |
| 1 | [Health Score](/customer-views/health-score-tab) | Overall score, category breakdown, trend, whether a drop is a config version change |
| 2 | [Revenue](/customer-views/revenue-tab) | MRR, outstanding invoices, days to renewal, cancel-at-period-end notices |
| 3 | [Usage](/customer-views/usage-tab) | Direction of core metrics over the same window as the overview |
| 4 | [Calls](/customer-views/calls-tab) | Last call, sentiment, action items, risk/growth signals in the transcript |
| 5 | [Support](/customer-views/support-tab) | Open tickets, age, escalations, resolution time |
| 6 | [Market Signals](/customer-views/market-signals-tab) | Recent external news (funding, hiring, layoffs) |
| 7 | [Opportunities](/product/opportunities) | Open expansion or renewal deals from the CRM |
| 8 | [Projects](/product/projects) | Onboarding or success-plan status, overdue milestones |
Do not treat the AI Insights blurb or a notebook draft as the system of record. Accept notebook text only after you have checked the tabs the draft cites. Every AI surface in Quivly is scoped to this customer and this org — still verify numbers before a customer meeting.
***
## Write the review document
Notebooks live on the customer. The AI reads that customer's calls, revenue, tickets, usage, and health. It cannot pull other customers.
Open **Notebooks** on the customer. Start empty, or run **Write with AI**.
Use a saved [skill](/product/skills) (templates include **QBR Prep** and **Sales Handoff Brief**), a free-form prompt, or both. In the editor, `/` inserts at the cursor.
Streamed text stays highlighted until you **Accept**, **Discard**, or **Retry**. Accepted blocks get a **Sources** line for the platforms the model actually queried.
The rest is a normal rich-text editor (headings, lists, tables). Edits autosave. Generation can run up to about 2.5 minutes.
An [agent](/product/agents) can create a notebook on a schedule (template **Renewal prep brief**) or on a health change. Add a Review step if a human should see it before the meeting. External tools can call `create_notebook` on the [MCP server](/developers/mcp-server).
***
## Ask follow-ups
[Ask Quivly](/product/ask-quivly) is org-wide chat, not limited to the open customer. For questions about *this* account, name the customer in the prompt, or stay in the notebook. Ask Quivly is read-only.
Useful prompts during prep:
* Category drivers for this customer's latest health score
* Open tickets older than N days
* Themes from calls in the review window
* MRR and outstanding invoices vs last quarter
***
## After the meeting
| Follow-up | Where |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Send the recap or schedule the next QBR | [Actions](/product/actions) (review the draft) or an [agent](/product/agents) App Action (Gmail / Calendar) behind a Review gate |
| Capture commitments as delivery work | [Projects](/product/projects) tasks and milestones |
| Change CRM stage or close a deal | Your CRM — Quivly does not write back |
| Recurring reviews | Agent on a **Schedule** trigger for a segment, creating a notebook each cycle |
***
## FAQ
No. Customizing Overview applies across customers for the organization layout you save. Header field choices and section order are shared.
No. Each notebook is scoped to one customer, enforced server-side. For a book-of-business view, use the [customer list](/customer-views/customer-list), a [dashboard](/dashboards/introduction), or Ask Quivly.
The score breakdown includes **Recommended Actions** generated from that calculation. They are suggestions. Signal-rule items in [Actions](/product/actions) are the inbox you work.
***
## Related guides
When the 360 is a save motion, not a QBR
Renewals, invoices, and pipeline
Usage trends and health usage scoring
Header fields, sections, and customize mode
# Identifying At-Risk Customers
Source: https://docs.quivly.ai/workflows/identifying-at-risk-customers
Complete workflow for finding and addressing customer churn risk
**Who is this guide for?** This workflow is for **Customer Success Managers and analysts** who need to proactively identify customers at risk of churning and take action to save them.
***
## Overview
Customer churn is expensive and often preventable. This workflow shows you how to use Quivly's health scores, usage data, support metrics, and market signals to identify at-risk customers before it's too late - and what to do about it.
**What You'll Learn:**
* How to filter for at-risk customers using health scores
* Which risk signals to look for in customer data
* How to prioritize your outreach (who needs help first)
* What actions to take based on risk level
* How to monitor progress over time
**Time Required:** 30-45 minutes for initial review, ongoing daily monitoring
***
## Understanding Risk Levels
Quivly categorizes customer health into 4 buckets. Here's what each means and how urgently you need to act.
**Meaning:** Severe churn risk, multiple red flags across categories
**Urgency:** Immediate action required (same day)
**Typical indicators:**
* No product usage in 14+ days
* Outstanding invoice 30+ days overdue
* Multiple unresolved high-priority support tickets
* Negative market signals (layoffs, executive departures)
* No engagement (calls, emails) in 60+ days
**Meaning:** Significant churn risk, concerning trends in 2-3 categories
**Urgency:** Action needed this week
**Typical indicators:**
* Usage declining 30%+ over last 30 days
* Upcoming renewal within 30 days with mediocre health
* Response times to your outreach increasing
* Support ticket volume spiking
* Key feature adoption dropping
**Meaning:** Stable but showing early warning signs
**Urgency:** Monitor closely, proactive check-in recommended
**Typical indicators:**
* Usage flat or slightly declining
* Some support issues but getting resolved
* Engagement is adequate but not enthusiastic
* No major red flags but trending in wrong direction
**Meaning:** Customer is thriving, engaged, and growing
**Urgency:** Low risk, focus on expansion opportunities
**Typical indicators:**
* Usage growing or stable at high levels
* Strong engagement (regular calls, QBRs)
* Low or no support issues
* Positive market signals (funding, hiring, growth)
* Actively adopting new features
***
## Step 1: Find At-Risk Customers
Let's identify which customers need your attention right now.
1. Click **Customers** in the left sidebar
2. You'll see your full customer portfolio
To see customers who need immediate attention:
1. Click the **Filter** control in the header
2. Pick the **Health Risk Level** field, operator **is one of**, and select **Critical** and **At Risk**
3. The filter applies immediately and shows as a chip above the table
This shows customers with scores 0-49 - your priority action list.
**Pro tip:** Save this as a custom view called "At-Risk Customers" so you can access it quickly every day without re-applying filters.
1. Click the **Health Score** column header
2. Select **Sort Ascending** (lowest scores first)
This puts the most critical customers at the top of your list.
**What you'll see:**
```
[🔴] Acme Corp - Score: 12 (Critical)
[🔴] Globex Inc - Score: 18 (Critical)
[🟠] Initech LLC - Score: 28 (At Risk)
[🟠] Umbrella Co - Score: 35 (At Risk)
...
```
For each at-risk customer, you'll see:
* **Company name and logo**
* **Health score badge** (color-coded)
* **Number of insights** (💡 icon with count)
* **Last activity date**
* **Industry and status**
The **insights count** shows how many AI-generated insights or market signals Quivly has detected. High insight counts often indicate significant changes happening at the account.
***
## Step 2: Investigate Risk Factors
For each at-risk customer, dig into WHY they're at risk. Open their profile and review these areas.
**Navigate to:** Customer Profile → **Revenue** tab
**Look for these red flags:**
| Signal | What It Means | Urgency |
| --------------------------------- | ----------------------------------------------------------------------- | --------- |
| **Outstanding balance > 30 days** | Payment issues, financial stress, or administrative oversight | 🔴 High |
| **Failed payment attempts** | Credit card expired, insufficient funds, or deliberate non-payment | 🔴 High |
| **Downgraded plan recently** | Reducing spend, possibly due to budget cuts or reduced value perception | 🟠 Medium |
| **Renewal in \< 30 days** | Renewal decision imminent, need to ensure they're ready to renew | 🟠 Medium |
| **MRR declining** | Canceling seats or downgrading features | 🟡 Low |
**What to check:**
* Current MRR vs 3 months ago (is it shrinking?)
* Invoice status (any past due?)
* Subscription details (active seats vs purchased seats)
* Renewal date (how soon?)
**Critical flag:** If a customer has an outstanding balance AND declining usage, this is a strong churn signal. They may already be planning to leave.
**Navigate to:** Customer Profile → **Usage** tab
**Look for these red flags:**
| Signal | What It Means | Urgency |
| -------------------------------- | ---------------------------------------------------------- | --------- |
| **No activity in 14+ days** | Customer has stopped using your product entirely | 🔴 High |
| **Usage down 50%+ from peak** | Significant drop in engagement, possible alternative found | 🔴 High |
| **Declining trend over 30 days** | Consistent decrease in activity | 🟠 Medium |
| **Low feature adoption** | Not discovering value in core features | 🟡 Low |
| **One power user only** | Heavy reliance on single user (risk if they leave) | 🟡 Low |
**What to check:**
* Usage trend chart (upward, stable, or declining?)
* Active users count (how many people actually using it?)
* Feature adoption (are they using core features?)
* Last activity timestamp (when did someone last log in?)
**Example usage patterns to watch:**
```
🔴 Critical Pattern:
- 30 days ago: 250 daily events
- 15 days ago: 120 daily events
- Today: 5 daily events
→ Sharp decline, investigate immediately
🟠 At Risk Pattern:
- Consistent decline: 200 → 180 → 160 → 140 events
→ Gradual disengagement, reach out proactively
🟢 Healthy Pattern:
- Stable or growing: 180 → 195 → 210 → 220 events
→ Customer is engaged, no immediate concern
```
Check if usage is down due to seasonality (holidays, weekends) or a genuine disengagement trend. Look at year-over-year data if available.
**Navigate to:** Customer Profile → **Support** tab
**Look for these red flags:**
| Signal | What It Means | Urgency |
| -------------------------------------- | ------------------------------------------------- | --------- |
| **High-priority ticket open > 7 days** | Critical issue unresolved, customer is frustrated | 🔴 High |
| **Ticket volume spiking** | Product issues or poor onboarding | 🟠 Medium |
| **Long resolution times** | Customer perceives slow or inadequate support | 🟠 Medium |
| **Escalated tickets** | Customer demanding leadership attention | 🟠 Medium |
| **Repeat issues** | Same problem keeps happening (quality issue) | 🟡 Low |
**What to check:**
* Open ticket count (how many unresolved issues?)
* Average resolution time (are we responding quickly?)
* Ticket sentiment (are customers frustrated in their messages?)
* Common issue categories (is there a pattern?)
**Critical flag:** If a customer has multiple unresolved tickets AND has stopped engaging with your team (not responding to support), they may have already mentally churned.
**Navigate to:** Customer Profile → **Calls** tab
**Look for these red flags:**
| Signal | What It Means | Urgency |
| -------------------------------------- | ------------------------------------------------------------ | --------- |
| **No calls in 90+ days** | Relationship is cold, no ongoing dialogue | 🟠 Medium |
| **Customer canceling scheduled calls** | Avoiding engagement, possible decision to leave already made | 🔴 High |
| **Short, transactional calls only** | No strategic discussions, just support issues | 🟡 Low |
| **Negative sentiment in transcripts** | Frustration detected in call recordings | 🟠 Medium |
**What to check:**
* Last call date (how long since we talked?)
* Call frequency trend (increasing or decreasing?)
* Call summaries (are they positive or negative?)
* Next scheduled call (do we have one on the calendar?)
Review call transcripts for keywords like "expensive," "not worth it," "considering alternatives," "budget cuts," or "frustrated." These are early warning signs.
**Navigate to:** Customer Profile → **Market Signals** tab
**Look for these red flags:**
| Signal | What It Means | Urgency |
| ------------------------- | --------------------------------------------------- | --------- |
| **Layoffs announced** | Budget cuts, possible software spend reduction | 🟠 Medium |
| **Executive departures** | Leadership changes, your champion may be gone | 🟠 Medium |
| **Funding difficulties** | Financial stress, may cut non-essential tools | 🟠 Medium |
| **Acquisition or merger** | Uncertainty, possible platform consolidation | 🟡 Low |
| **Negative press** | Company in crisis mode, not focused on your product | 🟡 Low |
**Positive signals to watch:**
| Signal | What It Means | Opportunity |
| --------------------- | ------------------------------------------- | ------------- |
| **New funding round** | More budget, possible expansion opportunity | 💰 Upsell |
| **Hiring spree** | Company growing, need more seats | 💰 Expansion |
| **Product launch** | Increased activity, possible new use cases | 💰 Cross-sell |
**What to check:**
* Recent signals in last 30 days
* Relevance score (is this signal actually about their business?)
* Signal sentiment (positive or negative?)
Market signals are external data Quivly collects from news, funding databases, and social media. They help you understand what's happening at the customer's business beyond what they tell you.
***
## Step 3: Prioritize Your Outreach
You can't save everyone at once. Prioritize based on urgency, ARR, and likelihood of success.
### Prioritization Framework
Use this matrix to decide who to contact first:
| Priority Tier | Criteria | Action Timeline |
| --------------- | ---------------------------------------------------------------------- | -------------------------------------- |
| **P0 - Urgent** | Score 0-24 AND (high ARR OR renewal \< 30 days OR outstanding balance) | Contact today |
| **P1 - High** | Score 25-49 AND high ARR | Contact this week |
| **P2 - Medium** | Score 25-49 AND medium ARR | Contact within 2 weeks |
| **P3 - Watch** | Score 50-74 with declining trend | Monitor, proactive check-in this month |
Save the filtered list as a view (e.g. "At-Risk Customers") and add the columns you need to prioritize — health score, MRR, days to renewal, last call. You can also ask [Ask Quivly](/product/ask-quivly) to rank your at-risk accounts.
For each customer, assign a priority tier:
**Example:**
```
Customer | Score | ARR | Renewal | Priority | Reason
---------------------------------------------------------------------
Acme Corp | 12 | $50K | 15 days | P0 | High ARR + imminent renewal + critical score
Globex Inc | 18 | $120K | 90 days | P0 | Very high ARR + critical score
Initech LLC | 32 | $8K | 45 days | P2 | Low ARR but needs check-in before renewal
Umbrella Co | 38 | $75K | 180 days | P1 | High ARR + high risk score
```
For each at-risk customer, identify who to contact:
1. Open the customer's **Overview** tab — contacts appear there and in the account sidebar
2. Look for:
* **Original buyer** (who signed the contract?)
* **Active users** (who actually uses the product?)
* **Executive sponsor** (who has budget authority?)
3. Check LinkedIn for recent job changes (did your champion leave?)
If your primary contact left the company (check LinkedIn), this is a **major churn risk**. You need to rebuild the relationship with their replacement ASAP.
***
## Step 4: Take Action
Now that you know who's at risk and why, here's what to do about it.
**Immediate actions for score 0-24:**
* Send email and Slack message (if applicable) **today**
* Subject: "Quick check-in - \[Your Product] at \[Company]"
* Tone: Helpful and concerned, not salesy
* Goal: Understand what's happening and how you can help
**Email template:**
```
Hi [Name],
I noticed [Company]'s usage of [Product] has declined recently,
and I wanted to reach out to see if there's anything we can do
to help.
Is everything okay? Are there any challenges or blockers we
should address?
I'd love to schedule a quick 15-minute call this week to make
sure you're getting value from [Product].
When works for you?
[Your Name]
```
* Alert your manager or account executive
* Share the customer profile and health score breakdown
* Discuss whether to offer concessions (discounts, extended trial, etc.)
* Get approval for any special interventions
* What were their original goals when they signed up?
* Are those goals still relevant?
* Have they achieved any wins using your product?
* What's blocking them from success?
**If they're willing to engage:**
1. Identify the core problem (lack of training, technical issues, poor fit, etc.)
2. Set specific, measurable goals for the next 30 days
3. Schedule weekly check-ins to monitor progress
4. Assign a dedicated point of contact (you or a solutions engineer)
**Example recovery plan:**
```
Goal: Increase daily active users from 2 to 10 by Feb 15
Week 1: Product training session with team leads (Jan 18)
Week 2: Follow-up on training, address technical blockers (Jan 25)
Week 3: Review usage data, celebrate wins (Feb 1)
Week 4: Business review, discuss renewal (Feb 8)
```
**If they're unresponsive:**
* Escalate to executive sponsor at their company
* Try different communication channels (phone, LinkedIn, etc.)
* Document all outreach attempts in your CRM
* Prepare for possible churn (forecast impact, plan backfill)
**Proactive actions for score 25-49:**
**Don't wait - be proactive:**
```
Subject: Let's make sure you're getting the most from [Product]
Hi [Name],
I wanted to check in on how things are going with [Product].
I noticed [specific observation - e.g., "usage has been a bit
quieter than usual" or "you have a few open support tickets"].
I'd love to schedule a brief call to:
- Make sure you're getting value from [Product]
- Address any challenges or questions
- Share some best practices from similar customers
Would you have 20 minutes sometime this week?
[Your Name]
```
Reference a specific data point ("I noticed...") to show you're paying attention and this isn't a generic email blast.
Provide immediate value without requiring a call:
* **Product training:** Invite them to an upcoming webinar or office hours session
* **Best practices guide:** Share a resource specific to their industry or use case
* **Success story:** Send a case study from a similar customer
* **New features:** Highlight features they haven't adopted yet that could help
**Example:**
```
"I noticed your team isn't using [Feature X] yet. We recently helped
[Similar Company] achieve [Outcome] by adopting this feature. Would
you like a quick walkthrough?"
```
If they agree to a call:
1. Screen-share their Usage tab in Quivly (or equivalent in your product)
2. Walk through usage trends: "Here's what we're seeing..."
3. Ask open-ended questions: "What changed around \[date when usage dropped]?"
4. Identify gaps: "Have you tried \[underutilized feature]?"
5. Set goals: "Let's aim to increase \[metric] by \[amount] over the next month"
**If renewal is within 90 days:**
Book a formal business review (QBR) to:
* Review goals vs achievements
* Demonstrate ROI and value delivered
* Discuss upcoming features on roadmap
* Address any concerns before renewal decision
**Monitoring actions for score 50-74:**
Configure Slack or email notifications for this customer if:
* Health score drops below 50
* Usage declines by 20% or more
* New high-priority support ticket is opened
* Negative market signal is detected
Go to **Settings** → **Notifications** to configure custom alerts for specific customers or customer segments.
Schedule a brief, friendly check-in:
```
Subject: Quick check-in - how's it going with [Product]?
Hi [Name],
Just wanted to touch base and see how things are going with
[Product]. Any questions or feedback?
Also, we just released [New Feature] - thought you might find
it useful for [their use case].
Let me know if you'd like a quick demo!
[Your Name]
```
Keep it light and helpful, not salesy. The goal is to maintain the relationship and show you're available if they need support.
Stay top-of-mind by sharing value:
* **Blog posts** about their industry or use case
* **Webinar invitations** for topics relevant to their business
* **Product updates** that might benefit them
* **Customer stories** from similar companies
***
## Step 5: Monitor Progress
Track whether your interventions are working.
1. Return to **Customers** page
2. Filter for customers you've recently engaged
3. Click on each customer and go to **Health Score** tab
4. Review the trend chart:
* **Upward trend (↗):** Your intervention is working!
* **Stable (→):** Keep monitoring, no change yet
* **Downward trend (↘):** Escalate, more intervention needed
Set a recurring calendar reminder every Monday to review health score changes for your at-risk customers.
For customers where low usage was the issue:
1. Go to Customer Profile → **Usage** tab
2. Compare current week to previous 4 weeks
3. Look for signs of recovery:
* Daily active users increasing
* Event volume trending upward
* New features being adopted
Record all outreach and results in your CRM:
* **Activity log:** Emails sent, calls held, outcomes
* **Next steps:** What you committed to do, when to follow up
* **Customer feedback:** What they told you about their experience
* **Status updates:** Progress toward recovery goals
If using Salesforce or HubSpot, log activities there so your entire team (sales, support, product) can see the engagement history.
At the end of each month, analyze:
* **How many at-risk customers did you identify?**
* **How many did you successfully save?** (health score improved or renewed)
* **How many churned anyway?** (despite your efforts)
* **What worked?** (which tactics were most effective)
* **What didn't work?** (which interventions failed)
Use these insights to refine your approach over time.
***
## Advanced Techniques
Not all churn risk is the same. Segment your at-risk customers by root cause:
**Segments:**
1. **Value risk:** Not seeing ROI, usage declining
* **Fix:** Product training, feature adoption campaigns, QBR to demonstrate value
2. **Financial risk:** Budget cuts, failed payments
* **Fix:** Flexible payment terms, downsell to smaller plan, demonstrate cost savings
3. **Relationship risk:** Poor support, disengaged CSM
* **Fix:** Dedicated support, executive sponsor engagement, apology + recovery plan
4. **Product fit risk:** Wrong use case, technical limitations
* **Fix:** Honest conversation, potential graceful exit, referral to better-fit solution
Focus your interventions based on the root cause, not just the score.
Look for leading indicators 60-90 days before renewal:
**Early warning signs:**
* Usage declining 3 months before renewal (not just 1 month)
* Engagement dropping off after onboarding completes
* Support ticket volume spiking in month 2-3 of contract
* Champion job changes detected via LinkedIn
Use Quivly's health score history to identify patterns:
* What health score at 90 days before renewal predicts churn?
* Which categories matter most? (e.g., is usage more predictive than support?)
Review score history against churned accounts to find your "churn threshold" - the score below which customers almost always churn. [Ask Quivly](/product/ask-quivly) can run this analysis across your portfolio.
Market signals can help you predict risk before it shows in usage data:
**Positive signals → Upsell opportunity:**
* Funding announced → "Congrats! As you scale, here's how we can help..."
* Hiring spree → "I see you're growing the team - need more seats?"
**Negative signals → Proactive support:**
* Layoffs announced → "I saw the news - let me know how we can support you during this transition"
* Executive departure → "I noticed \[Champion] left - who should I connect with on your team?"
**Set up alerts** for specific signal types in **Settings** → **Notifications**.
Create automated workflows for common risk scenarios:
**Example playbook: "30-Day No Usage"**
1. **Trigger:** Customer has 0 usage for 30 consecutive days
2. **Action 1:** Send automated "We miss you" email with helpful resources
3. **Action 2 (if no response after 7 days):** Assign to CSM for manual outreach
4. **Action 3 (if no response after 14 days):** Escalate to manager for executive outreach
Check if your CRM (Salesforce, HubSpot) or customer success platform supports these workflows.
***
## Measuring Success
Track these metrics to measure the effectiveness of your at-risk customer program:
| Metric | Definition | Target |
| ------------------------------- | ---------------------------------------------------------------------------- | --------- |
| **At-Risk Identification Rate** | % of churned customers who were flagged as at-risk 30+ days before churn | > 80% |
| **Intervention Rate** | % of at-risk customers you proactively contacted | > 90% |
| **Save Rate** | % of critical/high-risk customers who renewed or improved health score | > 50% |
| **Time to Outreach** | Days between customer flagged as at-risk and first outreach | \< 3 days |
| **Health Score Recovery** | % of at-risk customers whose score improved by 10+ points after intervention | > 40% |
***
## Common Mistakes to Avoid
**1. Waiting Too Long**
Don't wait until the renewal conversation to realize a customer is at risk. By then, they've already mentally decided to leave. Act when health scores first drop below 50.
**2. Focusing Only on High ARR**
Small customers churn too, and they add up. Don't ignore low-ARR at-risk customers - use automated playbooks for them if you can't manually reach out to everyone.
**3. Generic Outreach**
"Just checking in!" emails don't work. Reference specific data (usage decline, support tickets, market signals) to show you're paying attention.
**4. Ignoring the Data**
If health scores say a customer is critical but your gut says they're fine, trust the data. Investigate - you might discover issues they haven't told you about.
**5. Not Following Up**
One call doesn't save a customer. Create a recovery plan with specific milestones and follow up consistently until health improves.
***
## Next Steps
Fine-tune health score thresholds to better identify at-risk customers in your business
Track renewals and expansions to maximize customer lifetime value
Prepare comprehensive business reviews with data-driven insights
Drive feature usage to reduce churn risk
***
## Quick Reference Checklist
Use this checklist for your daily at-risk customer review:
* [ ] Filter customers by Critical + At Risk health scores
* [ ] Sort by score (lowest first) to prioritize
* [ ] Review top 5 most critical customers:
* [ ] Check revenue tab for payment issues or upcoming renewals
* [ ] Check usage tab for activity trends
* [ ] Check support tab for unresolved tickets
* [ ] Check market signals for external risk factors
* [ ] Check contacts tab to identify who to reach out to
* [ ] Send outreach emails to P0 customers (today)
* [ ] Schedule calls with P1 customers (this week)
* [ ] Set monitoring alerts for P2 customers
* [ ] Document all activities in CRM
* [ ] Review progress on previous week's at-risk outreach
**Need help?**
* Email support: [support@quivly.ai](mailto:support@quivly.ai)
* Share feedback on this workflow: [support@quivly.ai](mailto:support@quivly.ai)
# Product Adoption
Source: https://docs.quivly.ai/workflows/product-adoption
Monitor product usage metrics, score them in health, and turn drops or surges into drafted actions.
## Overview
Adoption in Quivly is the usage metrics you sync — events, seats, API volume, or whatever you map from your warehouse, PostHog, or the Push API — shown on the customer and folded into the **Product Usage** health category.
Use this workflow to:
* Confirm usage data is connected and mapped to customers
* Read trends on the [Usage tab](/customer-views/usage-tab)
* Put usage columns and filters on the [customer list](/customer-views/customer-list)
* Score usage in [health configuration](/health-scores/configuration)
* Draft outreach when usage drops or surges
Quivly does not write usage back to your product analytics or warehouse.
***
## What you need connected
Pick at least one product-usage source:
| Source | How it connects |
| ------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| [Snowflake](/integrations/warehouses/snowflake) or [BigQuery](/integrations/warehouses/bigquery) | Credentials; Quivly queries on a schedule |
| [PostHog](/integrations/product-usage/posthog) | OAuth or API key |
| [Usage Push API](/integrations/product-usage/api-overview) | HTTP events from your backend |
Customers must [link](/field-mappings/cross-system-linking) to those records (domain, external ID, or your mapping). A metric with no matching customer does not appear on a profile.
***
## Read the Usage tab
Open a customer → **Usage**.
### Time range and granularity
| Control | Options |
| --------------- | ------------------------------------------------------------- |
| **Time range** | Last 7 / 30 / 90 days, MTD, QTD, YTD, or a custom range |
| **Granularity** | Daily, weekly, or monthly — applies to every chart on the tab |
### Metric summary row
Up to six metrics across the top. Each card shows label, current value, a sparkline, and a trend percentage (up / down / flat). Click a card to highlight its chart.
### Charts
* **Product-grouped view** — when metrics are associated with products, they sit in collapsible product sections.
* **Flat view** — each metric is a time-series chart titled with the metric name and "Over Time", with a trend badge (growing, declining, or stable over the selected period).
Hover a chart for date and value. Color follows trend: green growth, red decline, indigo stable.
***
## Build a working list
Click **Customers**. Use **My Accounts** if you only want your book.
Any product usage metric can be a column, with period options **30d / 60d / 90d / 180d / 1y** and a trend indicator. Add the metrics you treat as adoption (for example weekly active users, or a core feature event).
Use numeric operators on those metrics: equals, greater than, less than, is empty, has value. Combine with **Health Risk Level** when a usage drop should only surface on unhealthy accounts.
Save as a [custom view](/customer-views/custom-views) (for example "Usage down 30d").
Sort the usage column ascending to put the quietest accounts first, or by health score if risk should lead.
If a usage column is empty for most rows, the warehouse/PostHog/Push source is not published, the metric is not mapped, or customers are not linking. See [customer information not linking](/troubleshooting/customer-information-not-linking).
***
## Score usage in health
Product Usage is one of five health categories. Enable it and set its weight under **Settings → Health Scores**. Weights for enabled categories must total 100%.
### Lookback
Product usage metrics support **30d, 60d, 90d, 180d, 1y**.
### Scoring methods
| Method | Description |
| ----------------------- | -------------------------------------------------------- |
| **Trend + Volume** | Combines usage volume with trend direction (recommended) |
| **Absolute Value** | Score from raw usage numbers |
| **Growth Percentage** | Score from percentage change vs the previous period |
| **Absolute Difference** | Score from change in units vs the previous period |
Each metric (except Market Signals) uses three thresholds that create four buckets, plus a direction (higher-is-better vs lower-is-better). See [configuration](/health-scores/configuration).
If a usage metric was configured and its data source is later removed, it shows as an orphaned metric with a warning badge. Save a draft, then [publish](/health-scores/configuration#saving-and-publishing) after you test.
On the customer **Health Score** tab, expand **Product Usage** for the category score, weight, contribution, and evidence. A declining usage category with a high weight is the usual adoption-risk pattern.
***
## Act
| Job | Where |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Explain why usage fell on one account | [Ask Quivly](/product/ask-quivly), or a usage [skill](/product/skills) in a [notebook](/product/notebooks) |
| Draft a recommendation on a usage drop or surge | [Signal rules](/product/signal-rules) — triggers **usage drops** or **usage surges** |
| Run a scheduled or threshold workflow (lookups → skill → Review → outreach) | [Agents](/product/agents) — template **Expansion spotter** (usage crosses a threshold) |
| Review and send the draft | [Actions](/product/actions) |
Signal-rule recommendations are always drafts. Use the sensitivity dial and quiet period so a noisy metric does not refill the inbox every day.
For expansion: high volume plus a healthy score is a stronger signal than high volume on a Critical account. Put health context next to usage before you pitch a plan change.
***
## Dashboards
The dashboard template library includes a **Product** category. Number and line widgets on usage metrics, filtered by segment or health bucket, give you a portfolio view the customer list cannot. See [dashboards](/dashboards/introduction).
***
## FAQ
Quivly scores the usage metrics you map. Feature-level adoption exists only if you send those events as metrics (warehouse, PostHog, or Push API) and attach them to customers.
Billing and usage are separate integrations. Paying in Stripe does not create warehouse rows. Confirm the usage source is published and the customer links on the identifier you map.
No. Usage tools are read-only. Outbound follow-up goes through agent steps or Actions you review.
***
## Related guides
Health-score workflow, including usage decline patterns
Renewals, invoices, and expansion pipeline
Time range, granularity, and chart layouts
How product usage gets into Quivly
# Revenue Management
Source: https://docs.quivly.ai/workflows/revenue-management
Find renewals, outstanding invoices, and expansion pipeline in Quivly, then act from the customer profile, Opportunities, agents, and notebooks.
## Overview
Revenue work in Quivly lives on the same customer as health, usage, and support. Billing data comes from your [billing integration](/integrations/billing/stripe). Deal data comes from your [CRM](/integrations/introduction). Quivly does not write back to either system.
Use this workflow to:
* Build a renewal and collections list from the [customer list](/customer-views/customer-list)
* Inspect MRR, invoices, and cancellation notices on the [Revenue tab](/customer-views/revenue-tab)
* Review expansion and renewal deals on [Opportunities](/product/opportunities)
* Draft outreach with [signal rules](/product/signal-rules), [agents](/product/agents), and [notebooks](/product/notebooks)
***
## What you need connected
| Source | What it supplies |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [Stripe](/integrations/billing/stripe) (or your billing provider) | MRR, ARR, subscriptions, invoices, renewal dates |
| [Salesforce](/integrations/crm/salesforce) or [HubSpot](/integrations/crm/hubspot) | Opportunities, stages, close dates |
| [Health scores](/health-scores/introduction) | Revenue category (MRR, outstanding balances, renewal timing) |
Without billing, the Revenue tab is empty. Without CRM, Opportunities has nothing to sync.
***
## Build a working list
Click **Customers**. Start from **All Customers** or **My Accounts** if you only own a book.
Use **+ Add column** or the header **Settings** gear. Include **MRR**, **Health Score**, and **Health Risk Level**. Add any billing or CRM fields you map — for example lifecycle stage — so you can sort without opening every profile.
Typical filters:
| Filter | Operator | Why |
| ----------------- | --------------------------- | --------------------------------- |
| Health Risk Level | is one of Critical, At Risk | Renewals that also look unhealthy |
| Segment | is | Enterprise or strategic book |
| Lifecycle Stage | is | Accounts already marked Renewing |
Conditions combine with AND. Save the result as a [custom view](/customer-views/custom-views) (for example "Renewals this quarter").
Sort by **MRR** descending when you are protecting revenue, or by **Health Score** ascending when risk should lead.
Days to renewal and outstanding balance are shown on each customer's [Revenue tab](/customer-views/revenue-tab). They are not default customer-list columns. Open the profile — or ask [Ask Quivly](/product/ask-quivly) — when you need those values for a specific account.
***
## Inspect the Revenue tab
Open a customer → **Revenue**.
### Metric cards
| Metric | What to use it for |
| ------------------- | ----------------------------------------------------- |
| **MRR** / **ARR** | Current recurring value |
| **Total Paid** | Historical collections |
| **Outstanding** | Unpaid invoices (highlighted if greater than zero) |
| **Days to Renewal** | Time until the current period ends (amber if overdue) |
| **Renewal Date** | Period end date |
### Subscriptions
Each active or trialing subscription shows name, status (Active, Trialing, Past Due, Canceled), MRR, line items, start/renewal/trial dates, and an orange notice if the subscription is set to cancel at period end. Canceled and expired subscriptions sit in **Past Subscriptions**.
### Invoices
The left panel lists invoices newest first, with status (Paid, Open, Draft, Uncollectible/Void), amount, due date, and whether payment was early, on time, or late. Select an invoice for totals, line items, billing reason, collection method, and **payment attempt count** when the provider sends it.
***
## Inspect Opportunities
Open **Opportunities** in the main nav for the org-wide pipeline, or the customer's **Opportunities** tab for that account only.
| View | Use |
| ------------ | -------------------------- |
| **Board** | Deals grouped by stage |
| **List** | Filterable, sortable table |
| **Calendar** | Deals by date |
Filter, sort, and save a named view. Deal data stays in the CRM — Quivly is the reading surface. Open pipeline also feeds the customer's revenue picture and [health score](/health-scores/introduction) context.
***
## Read revenue in the health score
On the customer **Health Score** tab, expand the **Revenue** category. Default revenue metrics cover MRR, outstanding balances, and renewal timing. A low score in a heavily weighted Revenue category moves the overall score more than the same drop in a light category. See [interpreting scores](/health-scores/interpreting-scores).
If Revenue is disabled or weighted to 0% in [configuration](/health-scores/configuration), it does not affect the overall score.
***
## Act
| Job | Where |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| Draft a renewal brief from live billing, contracts, usage, and health | [Notebook](/product/notebooks) on the customer, with a renewal or QBR [skill](/product/skills) |
| Ask who renews soon, who has outstanding invoices, or where MRR moved | [Ask Quivly](/product/ask-quivly) |
| Fire a drafted recommendation when a renewal is approaching | [Signal rules](/product/signal-rules) — trigger **approaching renewals** |
| Run a scheduled renewal brief, then pause for approval | [Agents](/product/agents) — template **Renewal prep brief** |
| Surface accounts ready to grow and draft outreach | [Agents](/product/agents) — template **Expansion spotter** |
| Review and send the draft email, Slack message, or calendar event | [Actions](/product/actions) |
Recommendations from signal rules are always drafts. Agents only send outbound messages if you published them that way; add a Review step to require approval.
***
## Portfolio dashboards
Under **Dashboards**, the template library includes a **Revenue** category. Use number, table, and trend widgets on customers, subscriptions, or opportunities, then apply dashboard-level date filters. See [creating dashboards](/dashboards/creating-dashboards).
***
## FAQ
No. Billing integrations are read-only. Change plans, collect payment, or void invoices in Stripe (or your billing provider).
No. The CRM stays the system of record. Use Ask Quivly or agents to analyze pipeline; close or re-stage the deal in Salesforce or HubSpot.
The billing integration is not connected, the customer is not linked to a billing record, or the subscription has no period end. See [customer information not linking](/troubleshooting/customer-information-not-linking).
***
## Related guides
Health-score workflow for churn risk, including revenue red flags
Prep a QBR or account review from the overview and notebooks
Usage trends, health usage scoring, and expansion from adoption
Metric cards, subscriptions, and invoice detail