New Contractor Alerts from Building Permits

A permit row is not a decision. A contractor starting new work is. This Actor reads public building-permit data from any Socrata open-data portal (hundreds of US cities and counties) and emits one signal per event worth reviewing:

Signal	Meaning
FIRST_SEEN_CONTRACTOR	Contractor has no permit in the baseline window — first activity observed
NEW_PROJECT_FOR_CONTRACTOR	A contractor active in the baseline has a new permit
ACTIVITY_CHANGE	The contractor has more than one permit in the current window
WATCHLIST_CONTRACTOR_ACTIVITY	The permit matches a name fragment on your watchlist

Choose this Actor when you need to know which contractors just started work in a jurisdiction — vendor compliance review, supplier or insurance sales prospecting, competitor tracking — without reading raw permit tables.

Not the right fit when you need homeowner contact data, permit valuations, or permits from portals that are not on Socrata. If you only want the normalized permit rows, use the free County Permit Normalizer.

Use cases

• Vendor and compliance review — flag contractors starting new work so their certificates are checked when it matters.
• B2B prospecting — suppliers, insurers and equipment sellers find contractors that are newly active in a county.
• Watchlists — follow specific contractors (e.g. "ELECTRIC", a company name) across a portal.
• Market monitoring — see how many new contractors appear per period.

Real run

San Diego County public permits (default input): 303 permits in the current window → 140 distinct contractors → 473 signals, of which 71 first-seen contractors. Signal types are not exclusive, so there can be more signals than permits.

Note: San Diego County's public dataset is a static archive last updated 2023-12-05. Windows are counted back from the dataset's own latest record, so the default run shows late-2023 activity. Point socrataHost / resourceId at a live portal (e.g. a city that updates weekly) for current signals.

Input example

{
  "socrataHost": "data.sandiegocounty.gov",
  "resourceId": "dyzh-7eat",
  "dateField": "issued_date",
  "currentWindowDays": 14,
  "baselineWindowDays": 90,
  "watchlist": ["ELECTRIC"],
  "fetchLimit": 2000
}

Input	What it does
socrataHost, resourceId	Any Socrata portal and dataset id (find one at opendatanetwork.com: search "building permits" + city)
dateField	The dataset's issue-date column (default issued_date)
currentWindowDays	Days counted as "current" (default 14)
baselineWindowDays	Comparison window right before it (default 90)
watchlist	Case-insensitive name fragments to flag
fetchLimit	Raw permit rows to read (default 2000)

Output example (one signal)

{
  "signal_type": "FIRST_SEEN_CONTRACTOR",
  "contractor": "ELEC ELECTRIC",
  "permit_id": "PDS2023-RESALT-015757",
  "current_activity": "Existing Residential Main Electrical Service Upgrade - 200A",
  "first_seen": true,
  "changed_state": "NEW",
  "source": "https://data.sandiegocounty.gov/resource/dyzh-7eat.json",
  "observed_at": "2026-08-30T10:00:44Z",
  "review_reason": "contractor not seen in the prior baseline window -- first real activity observed",
  "insurance_status": "NOT_OBSERVED"
}

Pricing

$0.02 per signal ($20 per 1,000).

The default San Diego run above (473 signals) costs about $9.46. Lower fetchLimit, shorten currentWindowDays, or use a watchlist to control volume, and set a maximum cost per run for a hard cap. Platform usage is included.

FAQ

Does it tell me if a contractor is insured or compliant? No. insurance_status is always NOT_OBSERVED — there is no certificate data source. A signal means "worth a review", never "compliant" or "non-compliant".

Which cities work? Tested on San Diego County. Other Socrata portals work when their permit dataset has a contractor column and a date column (set dateField to the date column's name). If a portal's columns are not recognized, open an issue with the dataset URL.

Why are signals older than today? Windows follow the dataset's latest record. Static archives produce historical signals; live portals produce current ones.

Can I run it weekly? Yes — save a task with your portal and schedule it.

Is the data public? Yes. Socrata open-data portals are government publications intended for reuse; requests are unauthenticated and rate-respecting.

Need a feature? Open an issue on the Issues tab — include your run ID.