Members

The members API is the member-level view of your book: who is green/yellow/red this period, a single member’s history, and where they were last seen. Every member carries a stable memberRefId, so the same real-world member resolves to the same id across every file and every month.

List members for a period

curl "https://api.commissionsight.com/v1/members?status=red&carrierId=$CARRIER_ID" \
  -H "Authorization: Bearer $TOKEN"

Query param	Notes
periodYear, periodMonth	Optional. Defaults to the latest period with data.
carrierId	Optional. Omit for all carriers.
status	Optional: green | yellow | red.
limit, offset	Pagination (default limit=50, max 200).

{
  "data": [
    {
      "memberRefId": "…", "carrierId": "…",
      "periodYear": 2026, "periodMonth": 4,
      "status": "red", "flags": ["DROPPED"],
      "commissionAmount": null, "prevCommissionAmount": 120.0,
      "comparedAgainstPeriod": "2026-03",
      "lastSeenPeriodYear": 2026, "lastSeenPeriodMonth": 3
    }
  ],
  "period": { "year": 2026, "month": 4 },
  "pagination": { "limit": 50, "offset": 0, "hasMore": true }
}

A single member

curl "https://api.commissionsight.com/v1/members/$MEMBER_REF_ID" \
  -H "Authorization: Bearer $TOKEN"

Returns the member’s latest unified record (name, ids, commission, plan, etc.) plus their policies. 404 if the id has never appeared.

Member journey (full audit history)

curl "https://api.commissionsight.com/v1/members/$MEMBER_REF_ID/journey" \
  -H "Authorization: Bearer $TOKEN"

The complete journey of a member — every period they appeared, the file it came from, the commission/premium, the status + flags, and the field-level changes — assembled in one call and ordered oldest → newest. This is the “entire story” view behind the member detail page in the app.

{
  "memberRefId": "…",
  "member": { "memberExternalId": "M-1042", "memberName": "Ada Lovelace", "email": "…", "carrierId": "…" },
  "firstPeriod": "2025-09", "latestPeriod": "2026-04", "periodCount": 8,
  "periods": [
    {
      "period": "2025-09", "periodYear": 2025, "periodMonth": 9,
      "status": "green", "flags": ["NEW"],
      "commissionAmount": 120.0, "premiumAmount": 1000.0,
      "policies": [
        { "policyRefId": "…", "policyNumber": "P-9001", "planName": "Gold PPO",
          "commissionAmount": 120.0, "premiumAmount": 1000.0, "effectiveDate": "2025-09-01", "renewalDate": "2026-09-01" }
      ],
      "file": { "fileId": "…", "fileName": "Humana - 0925.csv", "uploadedAt": 1727712000000 },
      "deltas": [],
      "firstSeen": true
    },
    {
      "period": "2026-04", "status": "yellow", "flags": ["COMMISSION_CHANGED"],
      "commissionAmount": 96.0, "premiumAmount": 1000.0,
      "policies": [ /* … */ ],
      "file": { "fileId": "…", "fileName": "Humana - 0426.csv", "uploadedAt": 1743552000000 },
      "deltas": [ { "field": "commission_amount", "prevValue": "120", "currValue": "96" } ],
      "firstSeen": false
    }
  ]
}

Each period names the source file (so you can trace any number back to the statement it came from — null if that file’s bytes were purged by retention), marks the first appearance, and lists the exact field changes detected entering that period. For multi-policy members, policies breaks the period down per policy.

A single policy’s journey

curl "https://api.commissionsight.com/v1/policies/$POLICY_REF_ID/journey" \
  -H "Authorization: Bearer $TOKEN"

Same shape, scoped to one policy (policy_ref_id is member-scoped). Use it to investigate a single policy’s commission history in isolation.

Reference ids on every export. Every results/compare CSV now includes the stable Member Ref ID (and Policy Ref ID where applicable). Drop that id into /v1/members/{memberRefId}/journey or /v1/policies/{policyRefId}/journey to pull the full history behind any row — the same ids power the clickable member/policy links in the app’s data tables.

Member timeline

curl "https://api.commissionsight.com/v1/members/$MEMBER_REF_ID/timeline" \
  -H "Authorization: Bearer $TOKEN"

A month-over-month ledger of status + flags, oldest → newest. This is the per-member history that makes fallout and reappearance explainable — a member whose most recent prior status was red and who returns is flagged REAPPEARED, against whatever period they were last present.

Where a member was last seen

curl "https://api.commissionsight.com/v1/members/$MEMBER_REF_ID/last-seen" \
  -H "Authorization: Bearer $TOKEN"

{
  "memberRefId": "…",
  "lastSeen": {
    "period": "2026-03",
    "periodYear": 2026, "periodMonth": 3,
    "commissionAmount": 120.0,
    "fileId": "…", "fileName": "Humana - 0326.csv", "uploadedAt": "2026-04-02T15:10:00.000Z"
  }
}

This resolves a dropped (or reappeared) member straight to the exact statement they last left on — the file name and upload time included — so an auditor can trace any flag to its source in one hop.