Carrier KPI threshold matrix: green, amber, red bands

What the KPI threshold matrix is

A carrier program is a preferred-contractor relationship: the network has agreed to route work to a carrier in exchange for that carrier meeting a standard of service. The KPI threshold matrix is where HQ writes that standard down in numbers instead of leaving it as a verbal understanding. It scores a carrier on four fixed operational metrics, cycle time, first contact, billing accuracy, and customer satisfaction, and for each one HQ enabled, declares a green band, an amber band, and (implicitly) a red band, plus whether a red reading is serious enough to auto-flip the carrier's qualification status.

This row appears on exactly one program type: carrier. It sits in the same structural slot the audit rubric occupies on vendor-approval programs, the type-specific standard-setting row, but scores an external partner on ongoing operational readings rather than a one-time weighted checklist. See hq-program-audit-rubric for that sibling row, and hq-program-detail-view for the full logic behind which rows a given program type shows.

Verinode does not decide whether a carrier stays on the network. It reads the bands HQ sets, reads whatever KPI readings have been captured against them, and lays out where each metric currently sits. Whether a carrier is renegotiated, put on probation, or kept as-is stays HQ's call.

Where to find it

1. 1Open Programs from the HQ sidebar at hq.verinode.ai/programs.
2. 2Find a carrier program in the Active, Drafts, or Sunset rows. Narrow the catalog first with the type-filter tabs if you run several (see hq-programs-type-filter-tabs).
3. 3Click the program's tile. You land on hq.verinode.ai/programs/[id].
4. 4Scroll past the hero panel and the Approved parties row to the KPI threshold matrix row.

If the program you clicked is not a carrier-type program, this row will not render at all, it is one of the type-gated rows described in hq-program-detail-view.

The four metrics

The matrix works with a fixed set of four KPIs. HQ cannot add a fifth or rename one, each metric has its own native unit and its own direction of "better" baked in:

| Metric | Unit | Direction of better | |---|---|---| | Cycle time | Days | Lower is better | | First contact | Hours | Lower is better | | Billing accuracy | Percent | Higher is better | | Customer satisfaction | Percent | Higher is better |

Cycle time and first contact measure speed, so a smaller number is the good outcome, faster claims turnaround, faster acknowledgment of a new file. Billing accuracy and customer satisfaction measure quality, so a bigger number is the good outcome. Each metric can be enabled or left out of the matrix independently, a carrier program does not have to score all four.

Green, amber, and red bands

For each enabled metric, HQ sets exactly two numbers: a green-at value and an amber-at value. There is no separate red-at field, red is whatever falls past the amber value on the wrong side. How the two numbers split the range depends on the metric's direction:

• Lower is better (cycle time, first contact): green-at is the ceiling for a green reading, amber-at is the ceiling for an amber reading. A reading at or under green-at is green. A reading over green-at but at or under amber-at is amber. A reading over amber-at is red. Verinode enforces green-at ≤ amber-at when you save, because a lower green ceiling than the amber ceiling would put the bands in the wrong order.
• Higher is better (billing accuracy, customer satisfaction): green-at is the floor for a green reading, amber-at is the floor for an amber reading. A reading at or above green-at is green. A reading below green-at but at or above amber-at is amber. A reading below amber-at is red. Verinode enforces green-at ≥ amber-at when you save.

When the editor opens on a metric you have not configured before, it pre-fills a starting pair of green-at and amber-at values so you are adjusting a real example rather than typing into a blank pair of fields. Those starting values are not a platform requirement, an admin can change either number to whatever fits the program:

| Metric | Starting green-at | Starting amber-at | |---|---|---| | Cycle time | 14 days | 21 days | | First contact | 4 hours | 12 hours | | Billing accuracy | 98% | 92% | | Customer satisfaction | 90% | 75% |

Reading the cycle-time row as a worked example: at the starting values, a carrier averaging 14 days or fewer to close a claim sits green, one averaging between 14 and 21 days sits amber, and one averaging past 21 days sits red.

Reading the row

Each enabled metric renders as its own tile:

• Label at the top left reads the direction arrow: ↑ better for the two higher-is-better metrics, ↓ better for the two lower-is-better metrics.
• Headline is the metric's own label: Cycle time (days), First contact (hours), Billing accuracy (%), or Customer satisfaction (%).
• Sub-line reads Green @ N · Amber @ N, the two numbers you set (in the metric's own unit, days, hours, or percent).
• Meta reads AUTO-DECERTIFY when a red reading on that metric is set to automatically flip the carrier's status, or REVIEW when a red reading instead routes to manual review.

After the last enabled metric tile, admins see one more tile: Edit thresholds, labeled KPI matrix, with a sub-line reading "N KPI(s) configured." Clicking it reopens the matrix editor with everything already saved.

Editing the matrix (admin only)

Click + Build the KPI matrix (when nothing is defined yet) or Edit thresholds (once at least one metric is configured) to open the Carrier KPI matrix modal.

The modal opens with this explanation: "Per-KPI red / amber / green bands. Red-band readings can auto-flip a carrier to probation (cron enforcement lands in a follow-on slice). Disable a metric to ignore it." Read that second sentence literally, it is covered in full under Auto-decertify below.

1. 1For each of the four metrics, check the box to enable it. A disabled metric drops out of the matrix entirely and does not appear on the row.
2. 2Once a metric is enabled, its direction label shows automatically ("lower is better" or "higher is better," this is fixed per metric and cannot be changed).
3. 3Set Green @ and Amber @ in the metric's native unit (days for cycle time, hours for first contact, percent for the other two).
4. 4Check Auto-decertify on red if a red-band reading on that specific metric should be treated as serious enough to automatically move the carrier to probation once enforcement ships (see the next section). Leave it unchecked to route red readings to manual review instead.
5. 5Optionally add a Description shown to carrier: free text covering how the bands are interpreted, the measurement window, or any exception clauses, this text is meant to be shared with the carrier and whoever audits it, not just kept internal.
6. 6Click Save matrix.

Verinode validates the matrix before saving and blocks the save with an inline message if:

• No metric is enabled at all ("Enable at least one KPI threshold.").
• A green-at or amber-at value is missing or not a number ("{metric}: thresholds must be numeric.").
• On a lower-is-better metric, green-at is set higher than amber-at ("{metric}: green must be <= amber when lower is better.").
• On a higher-is-better metric, green-at is set lower than amber-at ("{metric}: green must be >= amber when higher is better.").

There is no requirement to enable all four metrics, a carrier program scoring only cycle time and billing accuracy, leaving first contact and customer satisfaction disabled, is a valid matrix.

Auto-decertify on red: what is live today and what is not

Read this section before relying on the Auto-decertify on red checkbox for anything operational.

Live today: the checkbox itself, and the AUTO-DECERTIFY / REVIEW tag it drives on the row, are fully saved and displayed. Checking the box on a metric is a real, persisted declaration of intent, HQ is stating that a red reading on that metric is meant to be treated as automatic grounds for probation, not just a flag for someone to look at eventually.

Not yet built: nothing reads that declaration and acts on it automatically. The modal's own intro line says so directly, "cron enforcement lands in a follow-on slice", and the underlying record carries the same note: a red-band reading is meant to auto-flip the carrier's qualification status to probation once the enforcement job ships, but that job does not exist yet. Today, a carrier can sit at Qualified on the Approved parties row indefinitely with a KPI reading that would clearly fall into a red band under the matrix you configured, until an HQ admin notices and manually changes that carrier's status.

This is the same pattern as the vendor-approval program's audit rubric, which declares a pass threshold today with automatic enforcement of a below-threshold audit score also pending a follow-on slice. See hq-program-audit-rubric for that sibling explanation. Both features exist so the enforcement layer, once it ships, has a correct standard to read from, not so that a checked box does anything by itself right now.

Latest KPI snapshots row

This row is where actual readings against the matrix show up. It sits further down the same program detail page, after the network target and open violations rows, and only appears at all once at least one KPI reading has been captured for the program, there is no "+ add a snapshot" affordance on this page, readings arrive through the program's own data pipeline rather than being typed in here.

Each snapshot is a tile:

• Label is the KPI key itself, humanized to title case, for example a cycle_time_days snapshot shows as Cycle Time Days. This is a plainer rendering than the friendlier "Cycle time (days)" label used on the matrix row above it, both refer to the same metric.
• Headline is the reading's value, shown as a whole number when the value is an integer, or to two decimal places otherwise.
• Sub-line names the subject the reading is scoped to, plus the period it covers as a date range (period_start → period_end). The subject is one of three things: an enrolled franchisee's location name, an approved party's display name (for a carrier program, this is typically the carrier itself, tracked as an approved party), or the word Network when a snapshot is not tied to either, a network-wide aggregate reading rather than a single subject's.
• Meta reads when the snapshot was captured, relative to today.

Up to 20 of the most recent snapshots load per program, newest first by capture date.

This row is not exclusive to carrier programs. Any program type can show KPI snapshots once readings exist for it, but on a carrier program these snapshots are the natural evidence you check the KPI matrix's bands against, a snapshot reading in the red zone on a metric you've enabled is exactly the kind of thing the manual review in the previous section is watching for.

Empty states

KPI threshold matrix, non-admin viewer, nothing configured: "KPI thresholds not defined yet. Group admin can author the red / amber / green bands per metric from this row."

KPI threshold matrix, admin, nothing configured: a tile reading "+ Build the KPI matrix," with the sub-line "Cycle time · first-contact · billing accuracy · customer sat. Red-band can auto-decertify (follow-on)."

Latest KPI snapshots, zero captured: the row does not render at all, for anyone, admin or not. This matches how the platform treats read-only history rows generally, they are hidden rather than shown with placeholder copy when there is nothing behind them yet. See hq-program-detail-view for the full quick-reference table of which rows appear or disappear under which conditions.

Why this respects the HQ privacy boundary

The KPI matrix scores an external partner, the carrier, that the network has chosen to route work through, not any individual franchisee's business. HQ authors the bands, and any franchisee whose claims flow through this carrier already knows the relationship is being measured against a shared standard, that is the premise of a preferred-carrier program. Nothing on this row exposes a franchisee's own margins, job-level financials, or private carrier dealings outside this program. Where a KPI snapshot is scoped to a specific franchisee (its subject is a location name rather than "Network" or the carrier itself), that reading is the franchisee's own performance measured against the carrier relationship the whole network shares, the same category of aggregate HQ already sees across every program. See hq-programs for the full statement of what HQ sees and does not see inside a program.

Best-practice example

A network runs a carrier program with a national carrier as its one approved party. HQ enables all four metrics: cycle time (green at 12 days, amber at 18), first contact (green at 3 hours, amber at 8), billing accuracy (green at 97%, amber at 90%), and customer satisfaction (green at 88%, amber at 72%), with auto-decertify checked on cycle time and first contact but left unchecked on the two quality metrics, HQ wants speed misses to be a harder trigger than quality misses. Three months in, the Latest KPI snapshots row shows a run of readings for this carrier: cycle time drifting from 14 to 19 days over three consecutive snapshots, each one landing in the amber-to-red range against the 18-day amber threshold. Because auto-decertify enforcement has not shipped, none of that moves the carrier's status on the Approved parties row by itself, it stays Qualified. HQ catches the trend by reading the snapshots directly, and opens a renewal conversation with the carrier before the relationship needs a Probation flag at all, exactly the outcome the matrix is meant to support even without automatic enforcement behind it yet.

Related help articles

• hq-program-detail-view, the full program detail page and every row on it, including how the KPI matrix fits alongside approved parties, the network target, violations, and audits.
• hq-program-audit-rubric, the sibling type-specific standard-setting row for vendor-approval programs, and the closest parallel to this one's auto-decertify pattern.
• hq-program-approved-parties, the row directly above this one, where the carrier itself sits as an approved party with its qualification status, audit history, and (for vendor parties) negotiated rate.
• hq-programs, the Programs catalog: program types, creation flow, and the privacy boundary that governs everything HQ sees inside a program.
• hq-programs-type-filter-tabs, narrowing the catalog to carrier programs before you click in.
• hq-carrier-detail, the network-wide carrier overlay (Verinode Score, billed and collected, days to pay, satisfaction), a different surface scoring carriers across the whole network rather than one program's declared bands.
• hq-compliance, the network-wide compliance rollup that this program's violations and audit results feed into.