# WA Contractor License Status Delta (`titan_coder/wa-contractor-license-status-delta`) Actor

Watches named Washington State L\&I contractor licenses in the official registry and alerts only on a genuine status change (Suspended, Revoked, Out of Business, Inactive, Re-Licensed). For general contractors, homeowners, subcontractor vetting, insurers, due-diligence. Free when nothing changes.

- **URL**: https://apify.com/titan\_coder/wa-contractor-license-status-delta.md
- **Developed by:** [Radu Furtuna](https://apify.com/titan_coder) (community)
- **Categories:** Business, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$10.00 / 1,000 license status changeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## WA Contractor License Status Delta

Durable monitor for the official **L\&I Contractor License Data - General** registry, published by the
Washington State Department of Labor & Industries (L\&I) as open data on `data.wa.gov`. Watch specific
contractor licenses by their registration number and get notified only when their license status
genuinely changes. No API key needed, no login, no captcha.

### Source

`https://data.wa.gov/resource/m8qx-ubtq.json` — the Socrata Open Data API for "L\&I Contractor License
Data - General" (dataset id `m8qx-ubtq`). Confirmed live 14.09.2026: **161,190 rows**, updated by L\&I
(the underlying `rowsUpdatedAt` was hours old at the time of verification). `contractorlicensenumber` is
the dataset's unique, permanent identifier for one contractor license (exactly 12 characters, uppercase
letters/digits/asterisk, e.g. `ECOSTSC758NN`, `JUANHH*839MG`) — confirmed live by a full scan of all
161,190 values, not a sample. The `contractorlicensestatus` field observed live (14.09.2026) takes 10
values: `ACTIVE` (75,760), `EXPIRED` (61,331), `SUSPENDED` (9,781), `RE-LICENSED` (9,371),
`OUT OF BUSINESS` (4,702), `INACTIVE` (131), `SUPERCEDED` (95), `PASSED AWAY` (15),
`RESTORED FROM ARCHIVED` (3), `REVOKED DUE DEPT ERR` (1). A live SoQL measurement of
`contractorlicensesuspenddate` over the trailing 30 days found **1,517 transitions into a non-working
status**, of which **1,430** were specifically `SUSPENDED` — a real, measured volume of change.

### How it works

1. Each `watch` names exactly **one** contractor license by `contractorLicenseNumber` (the WA L\&I
   registration number as published in the registry — look it up at
   [secure.lni.wa.gov/verify/](https://secure.lni.wa.gov/verify/) if you only have a business name). One
   watch = one point query (`$where=contractorlicensenumber='<contractorLicenseNumber>'`) = one HTTP
   request per run.
2. The first check of a new watch establishes a baseline (no charge). Every later check compares the
   current status against the durable record of what it was last time.
3. Billing is tied **only to the `contractorlicensestatus`/`statuscode` fields** — not to business name,
   address, phone, principal name, or the routine `licenseexpirationdate` renewal that shifts for every
   actively licensed contractor as they renew. A status that changes and later reverts (e.g. suspended,
   then reinstated, then suspended again for a new violation) bills every genuine transition, not just
   the first one — never silently deduplicated against an earlier occurrence of the same status value.
4. Genuinely new (first found) or status-changed records are pushed to the dataset and billed once each
   (`license-status-changed`); a check that finds nothing new costs nothing beyond the fixed platform run
   cost.

### Input

```json
{
  "monitorId": "my-wa-lni-watch",
  "watches": [
    { "watchId": "new-sub-acme", "contractorLicenseNumber": "ECOSTSC758NN" }
  ],
  "notifyOn": "new_alerts",
  "webhookUrl": "https://example.com/webhook"
}
```

Add more contractor licenses later under the same `monitorId` — each watch keeps its own independent
history. A `watchId` is permanently bound to the `contractorLicenseNumber` it first saw; pointing the
same `watchId` at a different license number later fails the run instead of silently mixing histories.

`socrataAppToken` is optional — `data.wa.gov` does not require a key for this dataset, but a free Socrata
app token from your own account raises the anonymous request-rate ceiling if you run many watches across
many monitors.

### Output row (per change)

`watchId, licenseNumber, changeType ("new"|"status_changed"), status, previousStatus, statusCode,
businessName, licenseTypeCode, licenseTypeDesc, address1, address2, city, state, zip, phoneNumber,
licenseEffectiveDate, licenseExpirationDate, businessTypeCode, businessTypeDesc, specialtyCode1,
specialtyCode1Desc, specialtyCode2, specialtyCode2Desc, ubi, primaryPrincipalName, suspendDate,
monitorId, runId, discoveredAt, eventId, billed`

### Billing

Pay-per-event: `license-status-changed` — charged only for a watch's first found record (baseline is
free) or a genuine status transition since the previous check. Failed/blocked checks are never charged.

#### Delivery/billing guarantee: **at-most-once**, not exactly-once

The right to perform an irreversible action (dataset write + PPE charge) is granted by the only atomic
primitive Apify offers — `RequestQueue.addRequest(uniqueKey)` → `wasAlreadyPresent` — in a separate
named queue that acts as a permanent journal (`<prefix>-<monitorId>-claims`). The Apify Key-Value Store
has no CAS, no conditional write and no ETag, so it can only ever be a diagnostic state machine, never
the source of at-most-once.

Concretely: for one computed event, delivery and charging each happen **no more than once**. If the run
dies *after* taking the claim, the event may be **lost** (it stays `dataset_unknown`/`charge_unknown`
and is never re-delivered) — but you will never be billed twice. That is a deliberate trade: "never
overcharge" beats "never lose a row".

Boundaries of the guarantee, stated honestly:

- Between the internal lease check and the dataset write/charge there is an unavoidable TOCTOU gap; what
  actually protects your money is the claim gate, not the lease.
- The guarantee holds for as long as the named claims queue exists. Anyone with account access can
  delete or recreate it via Console/API, which starts the journal from zero. This is a boundary of any
  durable storage, not a defect of the protocol.
- The guarantee applies from the build in which the claim gate was introduced onward. Older builds must
  not keep running against the same `monitorId`.

### Important — read before relying on this for any hiring/contracting/insurance decision

**This registry is a publication of license status, not a certification of good standing or a complete
enforcement record.** L\&I maintains its own authoritative bond/insurance/complaint records; the public
dataset reflects what L\&I has published, which can lag real-world enforcement events. **This actor is an
informational monitor of CHANGES to that public publication — it is NOT a current "licensed to
contract" certification, NOT a complaint-history lookup, and NOT legal advice.** Always confirm directly
at [secure.lni.wa.gov/verify/](https://secure.lni.wa.gov/verify/) (or with L\&I directly) before acting on
any single entry — especially for hiring a subcontractor, homeowner contracting decisions, insurance
underwriting, or bonding/due-diligence decisions.

### Honest limits

- **The durable dataset is a delivery-attempt log, not a guaranteed mirror of the default dataset.**
  Each row is written to the durable dataset first, then mirrored to the run's default dataset before
  billing proceeds for that row. If the durable write succeeds but the default-dataset mirror write
  fails (e.g. transient Apify storage error), the item is marked `dataset_unknown`, billing for it is
  permanently blocked (fail-closed — we never charge for a row we can't confirm was delivered), and the
  run is not retried into re-creating that exact row. The durable dataset can therefore end up with a
  small number of orphan rows that were never mirrored and never billed. The **default dataset is the
  canonical log of rows successfully written to this run's output** (see its `run_summary` row) — but a
  default-dataset row does not by itself prove the row was billed: the row is written before
  `Actor.charge()` runs, so if charging then fails or comes back `charge_unknown`, the row is present but
  not confirmably paid. **`run_summary.eventsBilled` and Apify's own billing ledger are the source of
  truth for confirmed payment**, not the presence of a row in either dataset.
- **One watch = one contractor license, one request.** There is no bulk/roster mode — to track several
  subcontractors, add one watch per license (up to 30 per run). This keeps the network cost fixed and
  predictable regardless of the registry's total size (161k+ rows), and keeps each license's history
  independently auditable.
- **A "not found" result on the very first check of a watch is reported honestly, not as an error** —
  `coverage.watches[].matched: false`. A typo'd `contractorLicenseNumber` will simply never match; it
  costs nothing and is safe to correct and retry under the same `watchId`.
- **A license number that WAS found on a previous check but is NOT found on a later one** is treated as
  `source_access_limited` for that watch this run — no baseline/history update, no billing
  (**two-strike**: the history is never rewritten on a single disappearance; the very next run either
  finds the record again or reports `source_access_limited` again, indefinitely, until it is found).
  Unlike some sibling actors in this family (e.g. TX TREC, where an explicit `Deleted` status value is
  documented and confirmed live), this source does not document its behavior on a genuine record removal
  — so a disappearance is always treated as an honest signal of distrust in *this run's* snapshot, never
  silently reinterpreted as "the license was deleted from the registry".
- **Billing tracks only `contractorlicensestatus`/`statuscode`**, deliberately excluding
  `licenseexpirationdate` (which shifts routinely on every renewal for every actively licensed
  contractor) and address/contact/principal-name fields (which can change administratively — a move, a
  new phone number — without any change to license status). Those fields are still delivered in every
  row for context.
- We don't invent data: if the API ever returns something other than a bare JSON array, more than one
  row for a single `contractorlicensenumber` (violating the dataset's own uniqueness contract), or a row
  missing `contractorlicensenumber`/`contractorlicensestatus`/`statuscode`, the run reports it honestly
  (`source_access_limited`) instead of guessing.

Author: OmniCoder (https://t.me/OmniCoder)

# Actor input Schema

## `monitorId` (type: `string`):

Name of this monitor's durable history (a-z, 0-9, dash; up to 40 chars).

## `watches` (type: `array`):

1-30 objects: {"watchId": "new-sub-acme", "contractorLicenseNumber": "ECOSTSC758NN"}. contractorLicenseNumber is the WA L\&I contractor registration number as published in the registry (exactly 12 characters, letters/digits/asterisk, e.g. ECOSTSC758NN) — look it up at secure.lni.wa.gov/verify/ if you only have a business name. One watch = one contractor license. New licenses can be added later under the same monitorId.

## `socrataAppToken` (type: `string`):

Optional. data.wa.gov does not require a key for this dataset, but a free Socrata app token (from your own data.wa.gov account) raises the anonymous request-rate ceiling if you run many watches across many monitors. Leave empty for normal use — a handful of watches per run works fine without one.

## `notifyOn` (type: `string`):

new\_alerts — post the webhook only when new/changed paid status changes were delivered; always — post it every run; never — do not call webhookUrl at all.

## `webhookUrl` (type: `string`):

Optional. Receives a digest of delivered (paid) status changes as JSON. HTTPS only.

## Actor input object example

```json
{
  "monitorId": "my-wa-lni-watch",
  "watches": [
    {
      "watchId": "example-contractor",
      "contractorLicenseNumber": "ECOSTSC758NN"
    }
  ],
  "notifyOn": "new_alerts"
}
```

# Actor output Schema

## `results` (type: `string`):

Every row this run produced. Key fields: watchId, licenseNumber, changeType (new|status\_changed), status, previousStatus, businessName, licenseTypeDesc, city. Informational only — not legal advice or a current-standing certification.

## `coverage` (type: `string`):

What this run actually covered and what it charged for: per-watch status/reason/matched, records delivered and billed, requested/attempted/succeeded/failed watch counts. Enough to reconcile every charge against every row.

## `digest` (type: `string`):

A short human-readable summary of what this run found, written every run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "monitorId": "my-wa-lni-watch",
    "watches": [
        {
            "watchId": "example-contractor",
            "contractorLicenseNumber": "ECOSTSC758NN"
        }
    ],
    "notifyOn": "new_alerts"
};

// Run the Actor and wait for it to finish
const run = await client.actor("titan_coder/wa-contractor-license-status-delta").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "monitorId": "my-wa-lni-watch",
    "watches": [{
            "watchId": "example-contractor",
            "contractorLicenseNumber": "ECOSTSC758NN",
        }],
    "notifyOn": "new_alerts",
}

# Run the Actor and wait for it to finish
run = client.actor("titan_coder/wa-contractor-license-status-delta").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "monitorId": "my-wa-lni-watch",
  "watches": [
    {
      "watchId": "example-contractor",
      "contractorLicenseNumber": "ECOSTSC758NN"
    }
  ],
  "notifyOn": "new_alerts"
}' |
apify call titan_coder/wa-contractor-license-status-delta --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,titan_coder/wa-contractor-license-status-delta"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/N63MZzNXVcrCaZLgy/builds/o8QXRKtsHUeqBfxBV/openapi.json