Skip to content
CommissionSight Docs

Polling jobs

After upload, poll the job until status is completed (or failed).

Terminal window
curl https://api.commissionsight.com/v1/jobs/$JOB_ID -H "Authorization: Bearer $TOKEN"
{
  "id": "…",
  "status": "completed",
  "stats": { "rowCount": 1200, "mapped": 1198, "failed": 2, "green": 1100, "yellow": 80, "red": 18, "new": 12, "reappeared": 3 },
  "exceptionRowCount": 2,
  "_links": { "results": { "href": ".../results" }, "deltas": { "href": ".../deltas" }, "exceptions": { "href": ".../exceptions" } }
}

exceptionRowCount is the number of rows the ingest rejected (failed validation); when it’s > 0 an exceptions link is present (see Exception file).

Warnings

A job can complete successfully yet be structurally suspect. When so, it carries a warnings array of { code, severity, message } — surfaced in the web app and returned here. Codes include product_line_mismatch, missing_rate_schedule, zero_owed_coverage, low_owed_coverage, statement_total_variance, partial_statement_suspected, and identity_rebaseline_suspected. statement_total_variance fires only when you upload a statedTotal and the ingested commission sum diverges from it beyond tolerance; in that case stats also includes statedTotal, ingestedTotal, and variance so you can see the gap at a glance.

Two of these warnings exist to keep your churn numbers honest:

  • partial_statement_suspected — far more members “dropped” this period than remained. That usually means a partial or supplemental file (one legal entity, one state), not real attrition. Re-upload the full statement before acting on the drop list.
  • identity_rebaseline_suspected — the statement’s member ids changed since last period while the policy numbers stayed the same. Carriers occasionally re-issue member ids (plan-year changes, system migrations); when that happens, a naïve diff reads the entire book as dropped and re-added. CommissionSight detects the signature and tells you plainly: the mass dropped/new flags for this period reflect an id change, not real churn — fix the statement’s identity keying (or ask us to) and re-upload before trusting the period’s attrition. stats.idContinuity and stats.policyContinuity carry the underlying measurements on every job.

In practice these two guards are the difference between a dashboard you double-check and one you can act on: a churn spike that survives them is real and worth working the phones over.

Results grid

Terminal window
curl "https://api.commissionsight.com/v1/jobs/$JOB_ID/results?status=red,yellow&limit=100&offset=0" \
  -H "Authorization: Bearer $TOKEN"

Each row carries memberRefId, policyRefId, status, flags, commissionAmount, prevCommissionAmount, commissionOwed, and display fields (name, plan, policy). Page with limit/offset. Hand memberRefId/policyRefId to the journey endpoints to pull a record’s full history; both ids are also included on every CSV export.

status filter accepts a single value or a comma-separated set:

  • status=red — dropped members.
  • status=red,yellow — the “at risk” view: dropped and changed/reduced members together (what the at-risk dollar figure sums). The web dashboard’s “Review members” deep-links here.

commissionOwed is the per-member expected-vs-actual shortfall in dollars — the owed drilldown. It’s 0 when no contracted rate applies to that member, and it sums across the period to the rollup’s commissionOwed.

owedOnly=true returns only members with a shortfall (commissionOwed > 0) — the “underpaid” view. It evaluates owed across the whole period (not just the page), so the filter is complete; it combines with status (e.g. underpaid and at-risk).

{ "memberRefId": "…", "status": "yellow", "commissionAmount": 100.00,
  "prevCommissionAmount": 100.00, "commissionOwed": 20.00, "planName": "…" }

The rows come back as a flat array, so writing them straight to CSV is trivial (the web app offers one-click CSV export of this same grid and of any period comparison).

Exception file

If an ingest rejected any rows, download them (with the reason for each) to fix the source data:

Terminal window
curl -L "https://api.commissionsight.com/v1/jobs/$JOB_ID/exceptions" \
  -H "Authorization: Bearer $TOKEN" -o exceptions.csv

The response is a CSV: _row (the row number in the original file), _errors (why it was rejected), then every original column verbatim. Exception files are retained 30 days, then purged — after that the endpoint returns 404. See Data retention.

Retry

Terminal window
curl -X POST https://api.commissionsight.com/v1/jobs/$JOB_ID/retry -H "Authorization: Bearer $TOKEN"

Re-running a job is idempotent — unified records upsert by record_ref_id and statuses are recomputed deterministically.