US Contractor License Risk Event Monitor

Watch a book of California CSLB contractor license numbers and receive typed risk events when official CSLB Public Data Portal bulk files show material changes — suspensions, cancellations / portal absences, expirations, bond lapses, workers’-comp lapses, and reactivations — not another statewide contractor directory dump.

Honest title: CSLB-first scheduled poll / catch-up monitor. Multi-state registries (AZ ROC, FL DBPR, …) are roadmap only. Detection latency ≈ your schedule interval + CSLB weekly master refresh lag.

Value proposition

• Not a directory dump and not a Notion-only expiry checker: dataset emits typed risk events for agents / Clay / Slack / webhooks.

• Unlike check-priced multi-state wrappers that bill per license lookup (and may chain child scrapers), you pay only when a material risk event is delivered.

• Typed events: LICENSE_SUSPENDED, LICENSE_REVOKED, LICENSE_CANCELLED, LICENSE_EXPIRED, BOND_LAPSED, WORKERS_COMP_LAPSED, STATUS_REACTIVATED

• Official / public HTTP only — CSLB Public Data Portal License Master CSV (DownLoadFile.ashx?fName=MasterLicenseData&type=C). No paid Constructity and no $235 paid full-file order for MVP.

• Pay only for unique delivered risk events. First observation stores a baseline (no charge). Quiet days ≈ $0.

• Durable KVS checkpoint + event_uid dedupe.

PRODUCTION USE (required for real monitoring)

Store default ≠ product. Schema defaults use sourceMode=fixture so Apify Store daily auto-tests leave a non-empty health dataset without calling CSLB. That fixture path only writes a non-billable RUN_STATUS / FIXTURE_HEALTH row. It is not license monitoring.

For production monitoring you must:

1. Set sourceMode = live
2. Provide your licenseNumbers watchlist / book (CA CSLB)
3. Keep states including CA (only supported registry in MVP)
4. Schedule runs (e.g. daily / weekly aligned with CSLB master refresh) with fair-use requestPaceMs

Official references:

• CSLB Public Data Portal — Master List
• Direct CSV: https://www.cslb.ca.gov/OnlineServices/DataPortal/DownLoadFile.ashx?fName=MasterLicenseData&type=C
• CSLB Instant License Check (manual corroboration)

Data limitations (read before buying)

• Not real-time. CSLB regenerates the free statewide master roughly weekly. This Actor is a scheduled poll of that file.
• Free Public Data Portal master excludes licences that are cancelled, revoked, or expired non-renewable. When a watchlist license disappears from the master, we emit LICENSE_CANCELLED with subtype PUBLIC_MASTER_ABSENCE — honest that the free file does not distinguish cancel vs revoke vs expired-non-renewable. Use Instant Check for exact disposition.
• Suspensions that remain on the renewable master (e.g. Work Comp Susp, Contr Bond Susp) are observed as status / bond / WC field diffs.
• First run stores baselines only — you will not be charged for “current state” snapshots.
• Fair-use pacing applies; the live path downloads the full statewide CSV then filters to your book (CU cost is mostly download + parse).
• We cite California Contractors State License Board as the data origin. This Actor is not affiliated with or endorsed by CSLB.
• Multi-state expansion is not implemented yet — non-CA states are skipped with a warning.

Apify Store daily auto-test / default input

Field	Default
licenseNumbers	["1000000","999999"]
states	["CA"]
signalGroups	license, bond, workers_comp
sourceMode	fixture
emitFixtureDemoEvents	false
maxRunSeconds	300
maxEvents	500

On that path the Actor SUCCEEDS quickly, pushes exactly one RUN_STATUS / FIXTURE_HEALTH row (billable: false), and does not charge license-risk-event-delivered.

Input (summary)

Field	Notes
licenseNumbers	Watchlist (required)
states	MVP: CA only
signalGroups	license, bond, workers_comp
sourceMode	fixture (default) or live
emitFixtureDemoEvents	Default false
maxRunSeconds / maxEvents	Budgets
resumeFromCheckpoint	Default true
requestPaceMs	Fair-use delay (default 250)

Production example

{
  "licenseNumbers": ["1000000", "123456", "789012"],
  "states": ["CA"],
  "signalGroups": ["license", "bond", "workers_comp"],
  "sourceMode": "live",
  "maxRunSeconds": 360,
  "requestPaceMs": 250,
  "resumeFromCheckpoint": true
}

Output

Risk events (billable under PPE)

Typed rows include: license_number, business_name, state, event_type, event_subtype, changed_fields, previous_value, new_value, effective_date, evidence, summary, source_url, event_uid, billable: true.

RUN_STATUS (never billed)

Every successful run pushes one health row (FIXTURE_HEALTH | MONITOR_IDLE | CATCHUP_COMPLETE | HEALTH_OK).

Pricing

Pay-per-event: license-risk-event-delivered at $0.025 per delivered unique risk event ($25 / 1,000). Single tier (see docs/monetization.md and ADR 0010). Health / baseline / duplicate / fixture rows are never charged.

Local development

cd actors/us-contractor-license-risk-monitor
npm install
npm test
npm run build
# Store-safe fixture health:
apify run -p
# Demo typed events locally:
# set input emitFixtureDemoEvents=true (still sourceMode=fixture)

Attribution

Data originates from the California Contractors State License Board (CSLB) Public Data Portal. Not an official CSLB product.