No-Code Data Contract — Dashboard API Endpoints

Summary (3–6 bullets)

Defines read-only dashboard API contracts for no-code consumers.
Documents endpoint schemas, field meanings, and source tables/views.
Establishes rounding and precision expectations for money, percentages, and counts.
Enforces a strict no-recomputation rule for commission/business logic outside Repo B.
Captures planned visibility improvements (dataset routing + schema introspection).

When to use this (3–6 bullets)

When wiring no-code tools to dashboard endpoints.
When validating endpoint payload shape and data types.
When reviewing whether a requested derived field is allowed or prohibited.
When troubleshooting mismatches between frontend displays and backend data contracts.

What you’ll walk away with (2–5 bullets)

A clear list of approved read-only endpoints and expected response fields.
A practical boundary between safe no-code usage and forbidden logic duplication.
A quick checklist for data precision and source-of-truth expectations.

Date: 2025-12-19
Status: Planning Document (Read-Only Only)

Purpose

This document defines the data contract for no-code tools consuming dashboard API endpoints. All endpoints are read-only. No-code tools must NOT recompute commission math or create calculated fields that duplicate Repo B logic.

1. Endpoint Schemas

`/api/v1/ceo-metrics`

Method: GET
Query Parameters:

period_label (required): Date in YYYY-MM-01 format (e.g., 2025-07-01)

Response Schema:

{
  "period_label": "2025-07-01",
  "tenant_id": "creative_benefit_strategies",
  "total_businesses": 92,
  "total_employees": 1943,
  "gross_payout": 19187.77,
  "chargebacks": 1608.49,
  "net_payout": 17579.28,
  "business_owner_commission": 17579.28,
  "total_commission": 0.0,
  "total_policies": 1943,
  "total_lives": 1943
}

Field Descriptions:

total_businesses: Integer count of distinct businesses
total_employees: Integer count of distinct employees
gross_payout: Financial amount (rounded to cents)
chargebacks: Financial amount (rounded to cents)
net_payout: Financial amount (rounded to cents)
business_owner_commission: Financial amount (rounded to cents)
total_policies: Integer count (same as total_employees)
total_lives: Integer count (same as total_employees)

Source: analytics.ceo_snapshot view

`/api/v1/top-businesses`

Method: GET
Query Parameters:

period_label (required): Date in YYYY-MM-01 format
limit (optional): Integer, default 10

Response Schema:

{
  "businesses": [
    {
      "business_name": "Example Business",
      "total_revenue": 1234.56,
      "employee_count": 50,
      "rank": 1
    }
  ]
}

Field Descriptions:

business_name: String, normalized business name
total_revenue: Financial amount (rounded to cents)
employee_count: Integer count
rank: Integer ranking (1-based)

Source: analytics.top_businesses view

`/api/v1/top-agents`

Method: GET
Query Parameters:

period_label (required): Date in YYYY-MM-01 format
limit (optional): Integer, default 10

Response Schema:

{
  "agents": [
    {
      "agent_name": "JOHN DOE",
      "total_commission": 1234.56,
      "employee_count": 50,
      "business_count": 3,
      "rank": 1
    }
  ]
}

Field Descriptions:

agent_name: String, agent name
total_commission: Financial amount (rounded to cents)
employee_count: Integer count
business_count: Integer count
rank: Integer ranking (1-based)

Source: analytics.top_agents view

`/api/v1/growth-loss`

Method: GET
Query Parameters:

period_label (required): Date in YYYY-MM-01 format

Response Schema:

{
  "gained_employees": 1328,
  "lost_employees": 1122,
  "net_employee_change": 206,
  "businesses_count": 0
}

Field Descriptions:

gained_employees: Integer count
lost_employees: Integer count
net_employee_change: Integer count (gained - lost)
businesses_count: Integer count

Source: Calculated from analytics.business_growth_loss view

`/api/v1/growth-loss-details`

Method: GET
Query Parameters:

period_label (required): Date in YYYY-MM-01 format
limit (optional): Integer, default 10

Response Schema:

{
  "growth": [
    {
      "business_name": "Example Business",
      "net_employee_change": 50,
      "employee_change_pct": 25.5,
      "change_category": "Growth"
    }
  ],
  "loss": [
    {
      "business_name": "Another Business",
      "net_employee_change": -30,
      "employee_change_pct": -15.0,
      "change_category": "Loss"
    }
  ]
}

Field Descriptions:

business_name: String, normalized business name
net_employee_change: Integer count (can be negative)
employee_change_pct: Float percentage (rounded to 2 decimal places)
change_category: String enum (“Growth”, “Loss”, “Stable”)

Source: analytics.business_growth_loss view

`/api/v1/new-lost-businesses`

Method: GET
Query Parameters:

period_label (required): Date in YYYY-MM-01 format

Response Schema:

{
  "new": [
    {
      "business_name": "New Business",
      "current_employees": 25,
      "net_employee_change": 25,
      "employee_change_pct": null,
      "change_category": "New Business"
    }
  ],
  "lost": [
    {
      "business_name": "Lost Business",
      "previous_employees": 15,
      "net_employee_change": -15,
      "employee_change_pct": null,
      "change_category": "Lost Business"
    }
  ],
  "summary": {
    "new_count": 55,
    "new_employees": 1151,
    "lost_count": 54,
    "lost_employees": 1113
  }
}

Field Descriptions:

new: Array of new businesses (present in current period, absent in previous)
lost: Array of lost businesses (present in previous period, absent in current)
summary.new_count: Integer count
summary.new_employees: Integer count
summary.lost_count: Integer count
summary.lost_employees: Integer count

Source: raw.stage1_snapshots (FULL OUTER JOIN logic)

`/api/v1/business-health`

Method: GET
Query Parameters:

period_label (required): Date in YYYY-MM-01 format

Response Schema:

{
  "health_distribution": [
    {
      "category": "Healthy",
      "count": 50,
      "percentage": 54.35
    },
    {
      "category": "At Risk",
      "count": 30,
      "percentage": 32.61
    },
    {
      "category": "Critical",
      "count": 12,
      "percentage": 13.04
    }
  ]
}

Field Descriptions:

category: String enum (“Healthy”, “At Risk”, “Critical”)
count: Integer count
percentage: Float percentage (rounded to 2 decimal places)

Source: analytics.business_growth_loss view

2. Rounding Rules

Financial Fields

Rounding: To cents ($0.01)
Precision: 2 decimal places
Examples: 19187.77, 1608.49, 17579.28

Percent Fields

Rounding: To basis points (0.01%)
Precision: 2 decimal places
Examples: 25.50, -15.00, 54.35

Count Fields

Rounding: None (integers)
Precision: Whole numbers only
Examples: 92, 1943, 55

3. Source Tables/Views

Endpoint	Primary Source	Secondary Source	Notes
`/api/v1/ceo-metrics`	`analytics.ceo_snapshot`	`processed.stage3_snapshots` (for agent commissions)	View aggregates Stage 1 data
`/api/v1/top-businesses`	`analytics.top_businesses`	None	Pre-aggregated view
`/api/v1/top-agents`	`analytics.top_agents`	None	Pre-aggregated view
`/api/v1/growth-loss`	`analytics.business_growth_loss`	None	View with LAG() window functions
`/api/v1/growth-loss-details`	`analytics.business_growth_loss`	None	Same view, filtered and sorted
`/api/v1/new-lost-businesses`	`raw.stage1_snapshots`	None	FULL OUTER JOIN logic
`/api/v1/business-health`	`analytics.business_growth_loss`	None	View with categorization

Partitioning: All tables/views partitioned by period_label (DATE) and tenant_id (STRING) Dataset Routing: Controlled via environment variables:

BQ_DATASET_ANALYTICS (default: payroll_analytics)
BQ_DATASET_RAW (default: payroll_raw)
BQ_DATASET_PROCESSED (default: payroll_processed)

4. “No Recomputation Allowed” Warnings

⚠️ CRITICAL: No-Code Tools Must NOT Recompute Commission Math

Explicit Rules:

Read-Only Only: All endpoints are read-only. No write-back functionality exists or is planned.
No Calculated Fields: No-code tools must NOT create calculated fields that duplicate Repo B logic (e.g., net_payout = gross_payout - chargebacks).
Authoritative Source: Repo B outputs are the single source of truth for all financial calculations.
No AI Logic Changes: No-code tools must NOT modify commission calculation logic.

What No-Code Tools CAN Do:

✅ Read data from endpoints
✅ Filter and sort data
✅ Format data for display
✅ Aggregate data for visualization (e.g., sum totals, count items)
✅ Create derived metrics for display (e.g., “Total Revenue per Employee” = total_revenue / employee_count)

What No-Code Tools CANNOT Do:

❌ Recompute commission splits (agent vs owner)
❌ Modify financial calculations
❌ Create calculated fields that duplicate Repo B business logic
❌ Write data back to BigQuery
❌ Modify source data

Rationale

Repo B implements authoritative commission calculation logic with:

Decimal-safe financial calculations
Multi-stage data processing (Stage 1 → Stage 3 → Analytics)
Business rule enforcement (e.g., agent commission allocation)
Audit trail and reconciliation

No-code tools that recompute this logic would:

Create duplicate, potentially inconsistent calculations
Bypass business rule enforcement
Break audit trail
Risk financial discrepancies

5. Dataset Routing Visibility (PLANNED)

Status: Planning phase (not implemented)

Proposed Implementation

Option A: Response Header

Add header: X-Dataset-Routing: analytics=payroll_analytics_shadow,raw=payroll_raw_shadow,processed=payroll_processed_shadow
Purpose: Enable no-code tools to verify which datasets are active
Implementation: Add to all API responses

Option B: System Info Endpoint

Endpoint: /api/v1/system-info
Returns: {"datasets": {"analytics": "payroll_analytics_shadow", "raw": "payroll_raw_shadow", "processed": "payroll_processed_shadow"}}
Purpose: Enable no-code tools to query active dataset routing
Implementation: New read-only endpoint

Recommendation: Option A (response header) — simpler, no new endpoint needed

6. Schema Introspection (PLANNED)

Status: Planning phase (not implemented)

Proposed Implementation

Endpoint: /api/v1/schema/{endpoint_name} Example: /api/v1/schema/ceo-metrics Response:

{
  "endpoint": "/api/v1/ceo-metrics",
  "fields": [
    {
      "name": "total_businesses",
      "type": "integer",
      "description": "Total number of distinct businesses"
    },
    {
      "name": "gross_payout",
      "type": "float",
      "description": "Total gross payout before chargebacks (rounded to cents)"
    }
  ]
}

Purpose: Enable no-code tools to discover available fields and types without parsing example responses Implementation: New read-only endpoint that returns schema metadata

7. Explicitly EXCLUDED

The following features are explicitly excluded from this data contract:

❌ Write-back functionality — No endpoints support writing data
❌ Calculated fields in no-code layer — No-code tools must not duplicate Repo B calculations
❌ AI logic changes — No AI-driven modifications to commission logic
❌ Commission math outside Repo B — All commission calculations must use Repo B outputs
❌ Any modification of financial calculations — Financial calculations are authoritative in Repo B

8. Versioning

Current Version: 1.0
Last Updated: 2025-12-19 Version History:

1.0 (2025-12-19): Initial data contract document

9. Support

Questions or Issues:

Review docs/DASHBOARD_WIRING_VALIDATION.md for wiring details
Review docs/SHADOW_PREFLIGHT_RESULTS.md for data validation results
Contact development team for schema changes

Note: This is a planning document. Dataset routing visibility and schema introspection features are planned but not yet implemented.

Start Here

Operate & Support

Reference

Build & Integrate

NO CODE DATA CONTRACT

No-Code Data Contract — Dashboard API Endpoints

Summary (3–6 bullets)

When to use this (3–6 bullets)

What you’ll walk away with (2–5 bullets)

Purpose

1. Endpoint Schemas

`/api/v1/ceo-metrics`

`/api/v1/top-businesses`

`/api/v1/top-agents`

`/api/v1/growth-loss`

`/api/v1/growth-loss-details`

`/api/v1/new-lost-businesses`

`/api/v1/business-health`

2. Rounding Rules

Financial Fields

Percent Fields

Count Fields

3. Source Tables/Views

4. “No Recomputation Allowed” Warnings

⚠️ CRITICAL: No-Code Tools Must NOT Recompute Commission Math

What No-Code Tools CAN Do:

What No-Code Tools CANNOT Do:

Rationale

5. Dataset Routing Visibility (PLANNED)

Proposed Implementation

6. Schema Introspection (PLANNED)

Proposed Implementation

7. Explicitly EXCLUDED

8. Versioning

9. Support

Start Here

Operate & Support

Reference

Build & Integrate

​No-Code Data Contract — Dashboard API Endpoints

​Summary (3–6 bullets)

​When to use this (3–6 bullets)

​What you’ll walk away with (2–5 bullets)

​Purpose

​1. Endpoint Schemas

​/api/v1/ceo-metrics

​/api/v1/top-businesses

​/api/v1/top-agents

​/api/v1/growth-loss

​/api/v1/growth-loss-details

​/api/v1/new-lost-businesses

​/api/v1/business-health

​2. Rounding Rules

​Financial Fields

​Percent Fields

​Count Fields

​3. Source Tables/Views

​4. “No Recomputation Allowed” Warnings

​⚠️ CRITICAL: No-Code Tools Must NOT Recompute Commission Math

​What No-Code Tools CAN Do:

​What No-Code Tools CANNOT Do:

​Rationale

​5. Dataset Routing Visibility (PLANNED)

​Proposed Implementation

​6. Schema Introspection (PLANNED)

​Proposed Implementation

​7. Explicitly EXCLUDED

​8. Versioning

​9. Support

No-Code Data Contract — Dashboard API Endpoints

Summary (3–6 bullets)

When to use this (3–6 bullets)

What you’ll walk away with (2–5 bullets)

Purpose

1. Endpoint Schemas

`/api/v1/ceo-metrics`

`/api/v1/top-businesses`

`/api/v1/top-agents`

`/api/v1/growth-loss`

`/api/v1/growth-loss-details`

`/api/v1/new-lost-businesses`

`/api/v1/business-health`

2. Rounding Rules

Financial Fields

Percent Fields

Count Fields

3. Source Tables/Views

4. “No Recomputation Allowed” Warnings

⚠️ CRITICAL: No-Code Tools Must NOT Recompute Commission Math

What No-Code Tools CAN Do:

What No-Code Tools CANNOT Do:

Rationale

5. Dataset Routing Visibility (PLANNED)

Proposed Implementation

6. Schema Introspection (PLANNED)

Proposed Implementation

7. Explicitly EXCLUDED

8. Versioning

9. Support