Comparisons

A comparison scores any two periods against each other and returns who continued, changed, dropped, reappeared, or is new between them — the same status engine that powers the monthly grid, pointed at the two periods you choose. Use it for MoM, QoQ, YoY, or any arbitrary pair.

Compare two periods

curl "https://api.commissionsight.com/v1/comparisons?from=2026-01&to=2026-04&carrierId=$CARRIER_ID&granularity=quarter" \
  -H "Authorization: Bearer $TOKEN"

Query param	Notes
from, to	Required, YYYY-MM. from is the baseline; to is the period being scored.
carrierId	Optional. Omit to compare across all carriers.
granularity	Optional label for the result: month | quarter | year (defaults to month).

{
  "from": "2026-01", "to": "2026-04", "carrierId": null,
  "summary": { "green": 8120, "yellow": 940, "red": 612, "new": 210, "reappeared": 34, "total": 9672 },
  "data": [
    {
      "memberRefId": "…", "status": "yellow", "flags": ["COMMISSION_CHANGED"],
      "commissionAmount": 142.0, "prevCommissionAmount": 120.0,
      "comparedAgainstPeriod": "2026-01",
      "memberName": "Jane Doe", "memberExternalId": "M-1001", "policyNumber": "P-77"
    }
  ],
  "deltas": [ /* every field that moved between the two periods */ ]
}

Each row carries the member’s name, external id, and policy number (when present) next to the status/flags and commission then-vs-now — readable and searchable without a second lookup. deltas lists each field that changed (prevValue → currValue), so a yellow row is never a black box.

When to use comparisons vs. reports

• /comparisons recomputes the diff from the underlying records for the exact pair you ask for — use it for precise member-level MoM/QoQ/YoY movement and field deltas.
• /reports/* reads fast pre-computed period rollups — use them for dashboards and trend charts.

Both are driven by the same scored data, so the headline counts agree.