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

# Custom Metrics

> Custom Metrics lets you define your own KPIs by choosing a measure, aggregation, filters, grouping, and chart type without writing code.

## Overview

While the built-in analytics modules cover common use cases, every mortgage operation has unique questions. Custom Metrics gives you a flexible query builder that lets you define, save, and evaluate metrics tailored to your specific needs.

## Creating a Custom Metric

To create a metric, navigate to **Analytics > Custom** and click the button to add a new metric.

### Metric Definition Fields

| Field                | Description                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Name**             | A short, descriptive name for the metric (up to 100 characters). Example: "Avg Loan Size - Purchase"       |
| **Description**      | Optional longer description (up to 500 characters) explaining what the metric measures and why it matters. |
| **Pin to Dashboard** | When enabled, the metric appears at the top of the custom metrics page for quick access.                   |

### Configuration

The metric configuration controls what data is queried and how it is processed.

#### Aggregation

Choose how to compute the result:

| Aggregation | Description                                           |
| ----------- | ----------------------------------------------------- |
| **Count**   | Number of matching loans                              |
| **Sum**     | Total of the selected field across all matching loans |
| **Average** | Mean value of the selected field                      |
| **Min**     | Minimum value of the selected field                   |
| **Max**     | Maximum value of the selected field                   |

#### Field

Select which loan field to aggregate:

| Field                   | Description                        |
| ----------------------- | ---------------------------------- |
| **Loan Amount**         | The principal loan amount          |
| **Broker Compensation** | Broker compensation / revenue      |
| **Net Loan Revenue**    | Net loan revenue after adjustments |
| **Gross Loan Revenue**  | Gross loan revenue                 |
| **Company Margin**      | Company margin on the loan         |
| **Origination Fees**    | Origination fees charged           |
| **Rate**                | Interest rate                      |

Note: When using the **Count** aggregation, the field selection is less important since Count simply counts matching records.

#### Date Field

Choose which date field is used for date range filtering:

| Date Field          | Description                            |
| ------------------- | -------------------------------------- |
| **Funded Date**     | The date the loan was funded (default) |
| **Closed Date**     | The date the loan closed               |
| **App Intake Date** | The date the application was received  |
| **Created Date**    | The date the loan record was created   |

#### Filters

Add one or more filters to narrow which loans are included in the calculation. Each filter specifies a field, an operator, and a value.

Available operators:

| Operator                  | Meaning                     |
| ------------------------- | --------------------------- |
| **Equals**                | Exact match                 |
| **Not Equals**            | Excludes matching values    |
| **Is One Of**             | Matches any value in a list |
| **Greater Than**          | Numeric comparison          |
| **Greater Than or Equal** | Numeric comparison          |
| **Less Than**             | Numeric comparison          |
| **Less Than or Equal**    | Numeric comparison          |

Example filters:

* Loan Purpose = Purchase -- Only purchase loans
* Loan Type is one of FHA, VA -- Only FHA and VA loans
* Loan Amount >= 500000 -- Only loans above \$500K

#### Group By

Optionally group results to see the metric broken down by a dimension:

| Group By         | Description                                   |
| ---------------- | --------------------------------------------- |
| **Loan Officer** | Group by loan officer                         |
| **Lender**       | Group by lender                               |
| **Lead Source**  | Group by lead source                          |
| **Loan Purpose** | Group by Purchase / Refinance                 |
| **Loan Type**    | Group by loan product type                    |
| **Channel**      | Group by Broker / Non-Delegated Correspondent |
| **Month**        | Group by calendar month                       |
| **Quarter**      | Group by calendar quarter                     |
| **Year**         | Group by year                                 |

When a group-by is set, the metric returns both an overall value and a breakdown by group, sorted by value descending.

#### Visualization

Choose how the metric is displayed:

| Visualization | Best For                                               |
| ------------- | ------------------------------------------------------ |
| **Card**      | Single-value KPIs (total volume, average loan size)    |
| **Bar**       | Grouped comparisons (volume by lender, units by LO)    |
| **Line**      | Time-series trends (monthly volume, quarterly revenue) |
| **Pie**       | Proportional breakdowns (loan type mix, purpose split) |
| **Area**      | Time-series with emphasis on cumulative volume         |

#### Comparison Period

Optionally enable a comparison to a prior time range:

| Comparison         | Description                                                                                                           |
| ------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **Prior Period**   | Compare against the immediately preceding period of equal duration. If you select Jan-Mar, the comparison is Oct-Dec. |
| **Year over Year** | Compare against the same date range in the previous year. If you select Q1 2026, the comparison is Q1 2025.           |

When enabled, the metric result includes both the comparison value and the percentage change.

## Evaluating a Metric

Once created, a metric can be evaluated for any date range. The evaluation engine applies the metric's filters, date range, and aggregation to matching loans. If a group-by is configured, results are broken down by that dimension. If a comparison period is enabled, prior-period values are calculated alongside the current period.

### Result Structure

Each evaluation produces:

| Result Field   | Description                                                                         |
| -------------- | ----------------------------------------------------------------------------------- |
| **Value**      | The primary computed value (e.g., total volume = \$15,000,000)                      |
| **Grouped**    | If group-by is set, an array of `{ label, value }` pairs sorted by value descending |
| **Comparison** | If comparison is enabled, the prior period value and the percentage change          |

## Managing Custom Metrics

### Pinning

Pin important metrics to keep them at the top of the dashboard. Pinned metrics appear first, followed by unpinned metrics sorted by display order and creation date.

### Editing

Click on a metric to modify its name, description, configuration, or pinned status. Changes take effect immediately for all future evaluations.

### Deleting

Deleting a metric hides it from the dashboard but retains the record.

## Example Metrics

| Name                   | Aggregation | Field               | Filters                 | Group By     | Viz  |
| ---------------------- | ----------- | ------------------- | ----------------------- | ------------ | ---- |
| Total Funded Volume    | Sum         | Loan Amount         | (none)                  | (none)       | Card |
| Avg Purchase Loan Size | Average     | Loan Amount         | Loan Purpose = Purchase | (none)       | Card |
| Volume by Loan Officer | Sum         | Loan Amount         | (none)                  | Loan Officer | Bar  |
| Monthly Revenue Trend  | Sum         | Broker Compensation | (none)                  | Month        | Line |
| Loan Type Mix          | Count       | Loan Amount         | (none)                  | Loan Type    | Pie  |
| FHA Volume by Quarter  | Sum         | Loan Amount         | Loan Type = FHA         | Quarter      | Area |
| Revenue by Lead Source | Sum         | Broker Compensation | (none)                  | Lead Source  | Bar  |
| Avg Rate by Lender     | Average     | Rate                | (none)                  | Lender       | Bar  |