What HQ sees vs. what stays private: the vendor aggregate boundary

Why this page exists

Verinode HQ is the network intelligence layer, not a window into any one franchisee's business. On Vendors, that boundary is not a policy statement sitting in a terms document, it is enforced in the query that builds the page. This article documents exactly what HQ can see about the vendors your network uses, what it can never see, and why the numbers behave the way they do, including cases where a vendor tile simply will not open past its headline row.

If you administer a franchise network, a multi-location enterprise, or a PE-backed platform of independently reporting locations, read this before you present Vendors data to a franchisee advisory council or use it in a vendor negotiation. The boundary described here is what makes those numbers safe to share back with the network in the first place.

The two network models, and why they see different things

Every HQ group has one of two data postures, set once by Verinode during onboarding and stored on the group record (the network data.entity_model):

• Independent operators (independent_operators), the default, and the safer posture. Each location is a separately owned and operated business that happens to share a brand, a set of standards, and a data pipeline into Verinode HQ. This is the standard franchise model: locations are franchisees, not company branches.
• Same entity (same_entity), the group is a single legal entity with multiple company-owned locations. There is no separate "operator" to protect from identification, because HQ already owns the underlying business at every location.

The distinction matters because everything on this page, cohort suppression, name anonymization, the aggregate-only card, exists to prevent HQ from being able to identify a specific independent franchisee's private vendor spend, satisfaction rating, or vendor relationship by elimination. In a same_entity network, there is no franchisee to protect, so that machinery is bypassed entirely and HQ sees full attribution.

Unless a franchisee explicitly asks you to name themselves in a comparison, treat every number on this page as network intelligence, not a lookup tool for one location's books.

Where to find it

Open Vendors from the HQ sidebar at hq.verinode.ai/vendors. The page is a single home view, no tabs to switch between, built from the same row-and-tile design language used across HQ (Network Health, Benchmarks, Programs).

What the page shows, row by row

Network Vendors (hero)

The top of the page reads a headline count, Network Vendors, the total number of distinct vendors (software, equipment, subcontractors, materials suppliers) in active use anywhere in your network, rolled up nightly from every franchisee's vendor relationships into one row per canonical vendor.

Beside the count, a pill shows one of three things depending on what data exists:

• "N off-program", when at least one active vendor-approval program exists in Programs and N vendors currently in use aren't on it. Colored Ember Red at 5 or more off-program vendors, Hard Hat Yellow below that.
• "N multi-franchisee", when no vendor-approval program exists yet, this shows how many vendors are used by more than one franchisee, i.e. where there's shared buying leverage to act on.
• "No leverage data yet", neutral, shown when neither of the above has data.

Below the pill, a subtext line adds context: the network's top vendor category by count (e.g. "Top category: Restoration Equipment (12)."), the single largest spend line by name ("Largest line: ServPro National."), and, critically, a count of vendors currently hidden from view: "N hidden as single-franchisee." That phrase is the privacy boundary surfacing itself directly on the hero, more on exactly what it means below.

Three secondary figures sit beside the hero:

• Network annual spend, the sum of network_annual_spend_cents across every vendor row, with a monthly run-rate underneath.
• Top vendor, the single largest network-monthly line item, by name and dollar amount.
• Network avg satisfaction, the network-wide average satisfaction rating (1 to 10 scale, one decimal), weighted by how many franchisees rated each vendor. Reads "Awaiting franchisee ratings" until enough locations have rated at least one vendor.

If the network hasn't onboarded any vendor data yet, the hero headline reads 0 and the subtext reads: "Vendor data will appear as franchisees register their software, equipment, and contractor relationships." Verinode never invites you to "add" a vendor here, this page only ever reflects data flowing up from franchisee-recorded relationships.

Local Network

Directly under the hero sits a row surfacing local-market vendor activity for the franchisee locations in your network (built from FranchiseLocalNetworkRow). This row follows the same privacy rules as everything else on the page: aggregate signal about what's active in the local market, never a single operator's private ledger.

Off Program

This row exists to answer one question: "which vendors are our locations paying, that HQ hasn't formally approved?" It only shows content once at least one active vendor_approval program exists in Programs (see hq-programs); until then it reads:

"No active vendor approval programs defined yet. Once HQ publishes a preferred-vendor program in /programs, drift against it will surface here."

Once a program exists, if every actively used vendor is already on it, the row reads:

"Every vendor in active network use is on an HQ-approved program. No drift to address."

Otherwise, each off-program vendor appears as a double-width tile: its network monthly spend (or "Off-program" if no spend is on file), the vendor name, how many franchisees use it and its humanized category (e.g. "3 franchisees · Restoration Equipment"), and a meta line reading "Not on an HQ-approved vendor program." Tiles are colored Ember Red and rendered in high-intensity "action" framing because this is a compliance gap HQ should act on.

Rate Drift

Sits beside Off Program because the two answer sibling questions: off-program is "wrong vendor," rate drift is "right vendor, wrong price." This row only lights up once at least one HQ-negotiated rate has been captured on an approved vendor party (program_approved_parties.terms.negotiated_monthly_cents). Until then:

"Rate drift surfaces once HQ captures negotiated rates on at least one approved vendor (program_approved_parties.terms.negotiated_monthly_cents). Until then this row stays quiet."

If negotiated rates exist and every vendor is holding at or below its negotiated rate:

"Every vendor with a negotiated rate is being paid at or below the captured rate. No drift to renegotiate."

Otherwise, each drifting vendor shows a percentage overage ("+18% over") or a raw dollar overage, the vendor name, "Median $X vs negotiated $Y," and the franchisee count. A vendor only drifts when the network's median per-franchisee monthly spend, not the network total, exceeds the negotiated rate plus its tolerance band. Median is used deliberately: comparing a network total against a single-location negotiated rate would always look like drift once more than one franchisee is using the vendor, even at perfect compliance.

Top Vendors, Renegotiation Candidates, Broadest Network Footprint, All Vendors

These four rows are the spend-and-footprint views:

• Top Vendors, the network's biggest cost lines by total monthly spend, franchisee count, category, and annual run-rate.
• Renegotiation Candidates, vendors where the top-quartile (p75) per-franchisee spend is at least 2× the median per-franchisee spend, meaning some locations are paying meaningfully more than others for the same vendor. Shown as a ratio ("2.3× median") alongside the median and p75 dollar figures. This is the row that tells you where a network-wide rate negotiation would recover the most.
• Broadest Network Footprint, vendors sorted by how many franchisees use them, regardless of dollar size. A vendor with wide adoption and no negotiated program yet is a candidate for one.
• All Vendors, every vendor in the rollup, sorted by network monthly spend, up to 24 shown, each tile carrying spend, franchisee count, category, average satisfaction, and average Verinode Score where available.

Every one of these rows only ever contains vendors that pass the K-anonymity floor described next, they are built from the filtered list, never the raw one.

The privacy boundary: K-anonymity on the vendor cohort

This is the mechanism that everything above defers to. In an independent operators network, HQ enforces a minimum-cohort rule before any per-vendor row is allowed to render:

A vendor's numbers only surface on this page, or open in its detail view, once enough distinct franchisees in the network use that vendor. A vendor used by too few franchisees stays out of every row above, out of the hero's vendor count breakdown, and out of the detail slider entirely, no matter how much you click.

Why this exists: if only one franchisee in a small network uses a given software platform or subcontractor, showing that vendor's monthly spend, satisfaction rating, or Verinode score to HQ is functionally the same as showing that one franchisee's private business data. Anonymizing the franchisee's name doesn't fix this, HQ already knows who's on the roster; a single-user vendor identifies the operator by elimination even with the name stripped. So Verinode suppresses the row itself, not just the name on it.

What you'll actually see:

• The hero's subtext line quietly reports how many vendors are suppressed this way: "N hidden as single-franchisee."
• Those vendors never appear in Top Vendors, Renegotiation Candidates, Broadest Footprint, or All Vendors.
• The totalVendors count in the hero still reflects every vendor the network uses (including hidden ones), so the network-size number stays honest even while individual rows stay private.
• Network-wide aggregates, total spend, top category, aren't computed only from the hidden cohort in a way that would leak it back out; the suppression happens at the row level, not the totals level, and the totals are safe because they're sums across many vendors, not a single-vendor exposure.

If a franchisee later starts using an already-tracked vendor, or another franchisee adopts the same one, the vendor crosses the cohort floor and its row appears in the next nightly rollup, no manual action needed on your end.

Clicking into a vendor: the aggregate-only view

Clicking any vendor tile opens the vendor detail overlay, a centered modal over the Vendors page (the dedicated page at /franchise/vendors/[id] exists too, as a direct-link fallback if you land on a vendor from an external link or bookmark, and shows the identical privacy behavior).

If the vendor cleared the cohort floor, the overlay opens fully:

• A hero readout: category, program status (color-coded: Ember Red for Required, Deep Purple for Preferred, Deere Green for Approved, copper for Off program / not on any program), a Rate Drift flag if applicable, and the average Verinode Score with how many franchisees scored it.
• Headline KPIs: Annual spend, Franchisees using, Avg satisfaction (with peer rating count).
• A Cost distribution section: median monthly spend, p75 monthly spend (flagged "≥2× median" when the spread is wide), and total network monthly spend.
• If HQ has a negotiated rate on file for this vendor: a Negotiated rate vs network median block showing the negotiated rate, the network median, the dollar overage, and a Drift / On rate status.
• A Verinode score breakdown: the research-layer dimension scores behind this vendor's Verinode Score (the same breakdown IQ operators see on their own vendor cards), operator-agnostic and drawn from the shared intelligence catalog, not from any one franchisee's private rating.
• A Network team scores section: per-dimension medians aggregated from your own franchisees' private ratings of this vendor (your operator data.dimension_scores). Each dimension row shows a median score, a rater count, and a modal confidence tier, but only once at least a handful of franchisees have rated that specific dimension. Below that floor, the row reads "Insufficient ratings" instead of a number, the same K-anonymity discipline applied at the dimension level, not just the vendor level.
• A Programs row: every HQ program this vendor belongs to, its qualification tier, and its negotiated rate if set. If it's on no program, a single tile reads "Off program · This vendor isn't on an active HQ vendor-approval program."
• Per-franchisee participation: one row per franchisee using this vendor, their monthly spend, rating, and Verinode Score. Franchisee names here are not anonymized when the vendor has cleared the cohort floor, because at that point at least two franchisees are represented and no single row can be attributed by elimination. If no active relationships are on file: "No active franchisee relationships on file yet for this vendor. Rows populate after the nightly aggregator runs."
• Two optional actions in the header: Score deep-dive (score history, per-dimension trend, category weight profile, research narrative, entirely operator-agnostic) and Compare alternatives (N) (up to 4 same-category peers ranked by research score, each showing network footprint where already in use).

If the vendor has not cleared the cohort floor, the overlay opens to a single message and stops there. No headline KPIs, no cost distribution, no participation list, no score breakdown render at all:

Aggregate-only view. This vendor is currently used by fewer than 2 franchisees in your network. Per-vendor metrics are suppressed to protect operator privacy (single-franchisee identification risk).

The full-page fallback route (/franchise/vendors/[id]) adds one more sentence to the same message, pointing out that the vendor "will surface here in full once cohort size reaches 2+, or change the network data posture in Settings → Group → Data posture," which is the same entity_model toggle described above, only Verinode changes it, and only after confirming with you that your network's actual ownership structure supports it.

The documented PII-read carve-out (why this is safe, not an oversight)

HQ's standing privacy contract is that it never reads pii.* tables, the schema holding each franchisee's private operator-level business data, directly for display. The vendor detail overlay is the one place on the platform with a documented, narrow exception to that rule, and it's worth understanding exactly what it does and doesn't do, because it's the reason the Network team scores section above can exist at all.

When you open a vendor that has cleared the cohort floor, one server action reads your operator data.dimension_scores, the raw per-dimension ratings each of your franchisees privately recorded for that vendor, directly from the PII layer. That is the carve-out. It is bounded on every side:

• It only ever computes an aggregate. The raw per-operator scores are bucketed by dimension, a median is taken across every franchisee's rating, and only the median, a rater count, and a modal confidence label leave the function. No raw operator-level row is ever returned to the browser.
• It is gated by its own K-anonymity floor, separate from and in addition to the vendor-level cohort floor. Each dimension needs a minimum number of raters before its median is shown; below that, the dimension reads "Insufficient ratings" rather than a number computed from too few franchisees to anonymize safely.
• It never runs at all when the vendor itself is cohort-hidden. The cohort check happens first; if the vendor doesn't clear MIN_COHORT_K, this code path is skipped entirely, so a suppressed vendor never even triggers a PII read.
• It is documented in code, not silently present. The read is explicitly commented as a "PII READ EXCEPTION" carve-out from the HQ privacy contract, citing the condition under which it's allowed: on-click server actions may read pii.* if, and only if, the result is aggregated and the K-anonymity floor is enforced inline.
• A franchisee's own private "team rating" of a vendor never surfaces here. The score deep-dive panel explicitly passes a null team rating in the HQ context; that field is single-tenant by design and would breach the privacy contract if shown cross-tenant, so it simply isn't wired up on this surface at all.

The practical result: HQ gets to see "our network's franchisees rate this vendor's Reliability at a median of 4.2, from 6 raters, mostly at Observed confidence," which is genuinely useful network intelligence, and never gets to see which specific franchisee gave which score, or what any one franchisee privately thinks.

What HQ never sees on this page, full stop

Regardless of cohort size or entity model, HQ never sees, and this page never renders:

• The underlying job-level or invoice-level detail behind any franchisee's vendor spend, only the rolled-up monthly and annual totals.
• A single franchisee's raw dimension score for a vendor, only the network median once enough raters exist.
• A franchisee's private "team rating" of any vendor.
• Any vendor row where fewer than the cohort floor of franchisees use it, in an independent_operators network, no matter who is asking or why.

Same-entity networks: what's different

If your group's entity_model is same_entity, none of the cohort suppression above applies. Because there is no separately owned franchisee to protect from identification, every vendor row renders in full regardless of how many locations use it, per-location names pass through unanonymized on the participation list, and the "N hidden as single-franchisee" language never appears because nothing is hidden. This is a deliberate, narrower posture reserved for company-owned multi-location operations; independent franchise and association networks stay on independent_operators by default, and Verinode sets this value at onboarding, not through a self-service toggle on this page.

Related reading

• hq-overview, what HQ is, who it's for, and how it differs from an ERP or job-management tool.
• hq-programs, how vendor-approval programs, qualification tiers, and negotiated rates are set up; the source of the Off Program and Rate Drift rows on this page.
• network-health, the network-wide health rollup Vendors data feeds into.
• hq-compliance, how HQ tracks standards and program adherence across the network without reading franchisee-level detail.
• hq-benchmarks, how the same K-anonymity discipline applies to network benchmark comparisons.

Data sources