Auditing a book over time

CommissionSight keeps a complete, append-only history for every member, so you can audit an agency’s book at any depth — from a single member’s month-by-month story to a full reconciliation across every period you’ve ever ingested. Nothing is overwritten; every statement adds to the record.

The building blocks

Question	Endpoint
What happened to this member over their whole history?	`GET /v1/members/:memberRefId/timeline`
When/where was a member last seen?	`GET /v1/members/:memberRefId/last-seen`
What exactly changed in a given month (old → new value)?	`GET /v1/jobs/:jobId/deltas`
How does any period compare to any other?	`GET /v1/comparisons?from=&to=`
Who dropped or churned in a period?	`GET /v1/members?status=red` · `GET /v1/reports/attrition`
The grid for one statement	`GET /v1/jobs/:jobId/results`

Identity is stable across files: a member keeps the same memberRefId regardless of when a statement arrives, how the carrier formats it, or whether they disappear and come back. That’s what makes long-range auditing reliable.

1. A single member, end to end

Pull the member’s full month-over-month ledger — every period, status, and flag, back to the first time they ever appeared:

curl "$CS_BASE/members/$MEMBER/timeline" -H "Authorization: Bearer $CS_TOKEN"

{
  "data": [
    { "periodYear": 2025, "periodMonth": 11, "status": "green",  "flags": ["NEW"] },
    { "periodYear": 2025, "periodMonth": 12, "status": "green",  "flags": [] },
    { "periodYear": 2026, "periodMonth":  1, "status": "yellow", "flags": ["COMMISSION_CHANGED"] },
    { "periodYear": 2026, "periodMonth":  2, "status": "red",    "flags": ["DROPPED"] },
    { "periodYear": 2026, "periodMonth":  4, "status": "yellow",
      "flags": ["REAPPEARED", "REAPPEARED_WITH_DELTA", "COMMISSION_CHANGED"] }
  ]
}

This single response tells the whole story: enrolled in Nov, steady, commission changed in Jan, fell off the Feb statement, then reappeared in April with a different commission — and it’s flagged as such automatically. Reappearance is detected against the member’s most recent prior status, no matter how many months the gap spans.

For the precise dollars on the last statement they were on:

curl "$CS_BASE/members/$MEMBER/last-seen" -H "Authorization: Bearer $CS_TOKEN"
# → { lastSeen: { period, fileName, commissionAmount, fileId } }

2. Exactly what changed, with prior values

Every tracked-field change is stored as a delta with both the previous and current value, tied to the job (statement) that introduced it:

curl "$CS_BASE/jobs/$JOB/deltas?memberRefId=$MEMBER" -H "Authorization: Bearer $CS_TOKEN"

{ "data": [
  { "field": "commission_amount", "prevValue": "120.00", "currValue": "142.00", "changeType": "modified" },
  { "field": "plan_name",         "prevValue": "Gold PPO", "currValue": "Silver HMO", "changeType": "modified" }
]}

Tracked fields (commission, premium, renewal date, plan, email, phone) drive the yellow status; COMMISSION_CHANGED is always flagged separately so you can filter straight to money movement.

3. Reconcile the whole book — any period vs any period

To audit the book between two points in time — even a year or more apart — compare them directly. The comparison runs the same engine that powers monthly scoring, against whatever baseline you choose, so you can reach back as far as you have statements:

# Full-year movement across every carrier
curl "$CS_BASE/comparisons?from=2025-01&to=2026-01" -H "Authorization: Bearer $CS_TOKEN"

# Or scope to one carrier, or use quarter / year granularity
curl "$CS_BASE/comparisons?from=2025-10&to=2026-04&carrierId=$CARRIER&granularity=quarter" \
  -H "Authorization: Bearer $CS_TOKEN"

{
  "from": "2025-01", "to": "2026-01",
  "summary": { "green": 8120, "yellow": 940, "red": 612, "new": 210, "reappeared": 34, "total": 9672 },
  "data":   [ /* every member: name, external id, policy, status, flags, commission then-vs-now */ ],
  "deltas": [ /* every field that moved between the two periods */ ]
}

That single call answers “what changed across the book over this window”: who’s still on it (green), who changed (yellow, with the deltas), and who’s gone (red).

4. Churn & attrition for any period

curl "$CS_BASE/members?status=red&periodYear=2026&periodMonth=2" -H "Authorization: Bearer $CS_TOKEN"
curl "$CS_BASE/reports/attrition?period=2026-02" -H "Authorization: Bearer $CS_TOKEN"

Attrition is red ÷ members present the prior period (the projection-backed report approximates the denominator as present + dropped; use /comparisons for exact MoM movement). Each dropped member also carries their last-seen period and file, so you can go straight to the statement they fell off of.

How far back can you go?

As far as you’ve loaded. History is never truncated or rolled up destructively — every statement you ingest is retained as its own period, and the timeline, deltas, and comparisons all read from the full record. Load a carrier’s last several years of statements and you can audit the entire book across that whole span, member by member.

Auditor’s recipe

Scope — GET /v1/jobs to confirm which carriers/periods are loaded.
Book-level movement — GET /v1/comparisons?from=<start>&to=<end> for the audit window.
Drill in — for any flagged member, GET /v1/members/:id/timeline + GET /v1/jobs/:job/deltas?memberRefId=:id.
Trace drops — GET /v1/members/:id/last-seen to find the exact statement a member left on.
Export — pull GET /v1/jobs/:job/results (or GET /v1/comparisons) for the working papers.