# Colorado Contractor Leads & Business Records (`muhammadafzal/colorado-contractor-leads`) Actor

Find Colorado electrical and plumbing contractors with license status, dates, locations, verification links, and matched business records. Free-plan runs return at most 5 records.

- **URL**: https://apify.com/muhammadafzal/colorado-contractor-leads.md
- **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community)
- **Categories:** Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 verified contractor records

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Colorado Contractor Leads & Verified Business Records

Find state-licensed Colorado electrical and plumbing contractors, then cross-check each company against Colorado Secretary of State business records. The Actor returns lead-ready license, location, expiration, business-standing, formation, principal-address, registered-agent, and source-verification fields from official public datasets.

This Actor is designed for sales territory research, supplier outreach, insurance and compliance workflows, contractor-directory maintenance, and license renewal monitoring. It uses Colorado's official open-data APIs directly—no login, cookies, browser automation, or third-party data provider is required.

### What it extracts

| Field group | Included fields |
|---|---|
| Contractor license | License number, contractor trade, license status, first issue date, last renewal date, expiration date |
| Licensed company | Business name, named holder when present, city, state, ZIP code |
| License verification | Record-specific DORA verification URL and official source URL |
| Business verification | Match flag and transparent `EXACT`, `NORMALIZED`, `NONE`, or `NOT_REQUESTED` confidence |
| Colorado entity | Entity ID, legal entity name, standing, type, formation date, jurisdiction |
| Business location | Principal street address, city, state, and ZIP code |
| Registered agent | Registered-agent person or organization name from the public entity record |
| Provenance | Source dataset freshness and collection timestamp |

The state DORA dataset covers company contractor licenses for the electrical (`EC`) and plumbing (`PC`) trades. It does not represent every general contractor operating in Colorado: general-contractor licensing is commonly handled by cities and counties rather than through one statewide general-contractor registry.

### When to use it

Use the Actor to:

- build a list of active electrical or plumbing contractors by city or ZIP code;
- find newly issued contractor licenses for supplier, software, finance, or insurance outreach;
- identify licenses approaching a selected expiration date;
- verify a known contractor by company name or DORA license number;
- keep only businesses matched to a Secretary of State entity;
- keep only matched entities currently marked `Good Standing`;
- export consistent JSON, CSV, Excel, XML, or RSS data through Apify datasets.

Do not use it as proof that a contractor is qualified for a specific project, as a substitute for the live agency record, or as a source of phone numbers and email addresses. Those contact fields are not present in the source datasets and are not fabricated or inferred.

### Input

| Input | Default | Purpose |
|---|---:|---|
| `trades` | Electrical + plumbing | Choose `ELECTRICAL_CONTRACTOR`, `PLUMBING_CONTRACTOR`, or both |
| `licenseStatus` | `ACTIVE` | Return active licenses or all historical statuses |
| `cities` | empty | Exact, case-insensitive Colorado city filter |
| `zipCodes` | empty | Exact postal-code territory filter |
| `companyNames` | empty | Partial company-name search |
| `licenseNumbers` | empty | Exact DORA license-number lookup |
| `issuedAfter` | empty | Minimum issue date in `YYYY-MM-DD` |
| `expiresBefore` | empty | Maximum expiration date in `YYYY-MM-DD` |
| `verifyBusinessRecords` | `true` | Match licensees to Colorado business entities |
| `businessStanding` | `ANY` | Keep any license, matched entities, or Good Standing entities |
| `sortBy` | `NEWEST_LICENSE` | Sort by newest issue, soonest expiration, or business name |
| `maxResults` | `25` | Hard result and per-event spending cap, up to 10,000 for paid users; free-plan runs are capped at 5 |

#### Find active Denver contractors

```json
{
  "trades": ["ELECTRICAL_CONTRACTOR", "PLUMBING_CONTRACTOR"],
  "licenseStatus": "ACTIVE",
  "cities": ["Denver"],
  "verifyBusinessRecords": true,
  "maxResults": 25
}
```

#### Find newly licensed electrical contractors

```json
{
  "trades": ["ELECTRICAL_CONTRACTOR"],
  "issuedAfter": "2026-01-01",
  "businessStanding": "GOOD_STANDING",
  "sortBy": "NEWEST_LICENSE",
  "maxResults": 100
}
```

#### Find plumbing licenses expiring before a date

```json
{
  "trades": ["PLUMBING_CONTRACTOR"],
  "licenseStatus": "ACTIVE",
  "expiresBefore": "2027-03-01",
  "sortBy": "EXPIRING_SOON",
  "maxResults": 100
}
```

From the API, send the same JSON object as the Actor run input. AI agents can route directly from phrases such as “active Denver electricians,” “Colorado plumbing license 2225,” or “new Colorado electrical contractors in good standing” because each input and output field has a narrow semantic description.

### Output example

```json
{
  "licenseNumber": "102804",
  "licenseTypeCode": "EC",
  "trade": "Electrical Contractor",
  "businessName": "LG Electrical, LLC",
  "licenseHolderName": null,
  "licenseStatus": "Active",
  "licenseFirstIssuedDate": "2023-08-16",
  "licenseLastRenewedDate": "2026-10-01",
  "licenseExpirationDate": "2029-09-30",
  "city": "Littleton",
  "state": "CO",
  "zipCode": "80125",
  "licenseVerificationUrl": "https://www.colorado.gov/dora/licensing/Lookup/PrintLicenseDetails.aspx?cred=1530795&contact=1641517",
  "businessVerified": true,
  "businessMatchConfidence": "EXACT",
  "businessEntityId": "20228210491",
  "businessEntityName": "LG Electrical, LLC",
  "businessEntityStatus": "Good Standing",
  "businessEntityType": "DLLC",
  "businessFormationDate": "2022-12-13",
  "businessJurisdiction": "CO",
  "principalAddress": "9619 W Titan Rd Unit B",
  "principalCity": "Littleton",
  "principalState": "CO",
  "principalZipCode": "80125",
  "registeredAgentName": "LUKAS DAVID GARRISON",
  "businessRecordUrl": "https://www.sos.state.co.us/biz/BusinessEntityDetail.do?masterFileId=20228210491",
  "sourceDatasetUpdatedAt": "2026-09-12T04:14:11.000Z",
  "scrapedAt": "2026-09-12T10:00:00.000Z",
  "sourceUrl": "https://data.colorado.gov/d/7s5z-vewr"
}
```

`businessVerified` means the Actor found a deterministic exact or normalized-name match in the Secretary of State dataset. It does not imply endorsement, ownership confirmation, insurance coverage, or legal advice. When several entity rows share a name, the matcher prefers Good Standing records and uses matching city/ZIP data as deterministic tie-breakers.

#### Free-plan limit

Apify passes the requesting user's plan status to the Actor. To keep free testing useful and bounded, free-plan runs deliver no more than 5 records even when `maxResults` is higher. The run status and `SUMMARY`/`OUTPUT` explain when this cap was applied, including both `requestedMaxResults` and `effectiveMaxResults`. Paid-plan runs can use the requested `maxResults` up to 10,000. This is an Actor-level limit, not an Apify platform error.

### Pricing

The Actor uses transparent pay-per-event pricing.

| Event | Price |
|---|---:|
| Actor start | $0.00005 per run |
| Contractor record | $0.001 per dataset item |

A 10-record run costs up to **$0.01005** in Actor event charges. A 100-record run costs up to **$0.10005**. `maxResults` caps output records, and therefore caps record-event spend. Apify account-level spending limits still apply.

The runtime never manually charges these synthetic events. Apify charges one start event and one default-dataset-item event only after a schema-valid record is written.

### Reliability and data freshness

The Actor calls the official Colorado Information Marketplace APIs with bounded timeouts, four retry attempts, exponential backoff, and jitter. It records the source update timestamp in both output and the `SUMMARY`/`OUTPUT` key-value records. A valid search with no matches exits truthfully as `EMPTY`; bad combinations exit as `REJECTED`; source failures remain `FAILED` rather than being disguised as empty results.

Business matching is optional because it adds one or two official-source lookups per candidate. Disable `verifyBusinessRecords` for the fastest license-only export. Filtering by `MATCHED_ONLY` or `GOOD_STANDING` can require scanning more source rows than the delivered result count, but the Actor still stops at bounded pages and `maxResults`.

The DORA open dataset is updated on the schedule published by Colorado and is intended for research. For consumer-protection or contracting decisions, open the item-level `licenseVerificationUrl` and confirm the current agency record.

### Legal and responsible use

The output comes from public government records. Public availability does not remove your obligations under privacy, advertising, anti-spam, fair-credit, consumer-protection, or industry-specific laws. Use the data for legitimate purposes, minimize retained personal data, respect opt-outs, and do not make eligibility or adverse decisions solely from this dataset. Registered-agent names and principal addresses may identify individuals or home addresses.

For support, include the run ID, a redacted input example, the expected license or company, and the observed `SUMMARY`. Do not post personal data or Apify tokens in an issue.

# Actor input Schema

## `trades` (type: `array`):

Use this when selecting contractor categories. Choose electrical contractors, plumbing contractors, or both. Default: both state-licensed contractor types. This does not include municipal general-contractor licenses.

## `licenseStatus` (type: `string`):

Use ACTIVE for current lead lists or ALL for historical research. Default: ACTIVE. Status comes directly from the Colorado DORA public dataset.

## `cities` (type: `array`):

Use this when targeting Colorado cities. Enter exact city names such as Denver, Aurora, or Colorado Springs. Leave empty for statewide results; accepts up to 50 cities.

## `zipCodes` (type: `array`):

Use this for ZIP-level territory lists. Enter exact postal codes such as 80202; accepts up to 100. Leave empty to avoid ZIP filtering.

## `companyNames` (type: `array`):

Use this when looking up known contractors by legal or trade name. Partial, case-insensitive matching is supported, for example Summit Electric. Leave empty for category/location discovery; accepts up to 50 names.

## `licenseNumbers` (type: `array`):

Use this to verify exact Colorado DORA license numbers, for example 102804. Leave empty for discovery searches; accepts up to 100 numbers.

## `issuedAfter` (type: `string`):

Use this to find newer contractor licenses. Enter YYYY-MM-DD, for example 2025-01-01. Leave blank for no minimum issue date.

## `expiresBefore` (type: `string`):

Use this for renewal outreach or compliance checks. Enter YYYY-MM-DD, for example 2027-12-31. Leave blank for no maximum expiration date.

## `verifyBusinessRecords` (type: `boolean`):

Use this to match licensed company names against the Colorado Secretary of State business-entity dataset. Default: enabled. Adds entity standing, formation date, principal location, and registered-agent name; unmatched records remain explicit.

## `businessStanding` (type: `string`):

Use ANY to keep all license records, MATCHED\_ONLY to require a Secretary of State match, or GOOD\_STANDING to require a matched entity currently marked Good Standing. This filter applies after license retrieval.

## `sortBy` (type: `string`):

Use NEWEST\_LICENSE for prospecting, EXPIRING\_SOON for renewal workflows, or BUSINESS\_NAME for directory exports. Default: newest licenses first.

## `maxResults` (type: `integer`):

Use this to cap delivered records and PPE spend. Range: 1–10,000; default 25 and prefill 10. Free-plan runs are capped at 5 records; paid-plan runs honor the requested value. Each output record costs $0.001 plus one $0.00005 run-start event.

## Actor input object example

```json
{
  "trades": [
    "ELECTRICAL_CONTRACTOR",
    "PLUMBING_CONTRACTOR"
  ],
  "licenseStatus": "ACTIVE",
  "cities": [
    "Denver"
  ],
  "zipCodes": [],
  "companyNames": [],
  "licenseNumbers": [],
  "issuedAfter": "",
  "expiresBefore": "",
  "verifyBusinessRecords": true,
  "businessStanding": "ANY",
  "sortBy": "NEWEST_LICENSE",
  "maxResults": 10
}
```

# Actor output Schema

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

Schema-validated contractor license and business records.

## `dataset` (type: `string`):

Default dataset API endpoint.

## `summary` (type: `string`):

Outcome, counts, source freshness, and warnings.

# 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 = {
    "trades": [
        "ELECTRICAL_CONTRACTOR",
        "PLUMBING_CONTRACTOR"
    ],
    "licenseStatus": "ACTIVE",
    "cities": [
        "Denver"
    ],
    "zipCodes": [],
    "companyNames": [],
    "licenseNumbers": [],
    "issuedAfter": "",
    "expiresBefore": "",
    "verifyBusinessRecords": true,
    "businessStanding": "ANY",
    "sortBy": "NEWEST_LICENSE",
    "maxResults": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/colorado-contractor-leads").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 = {
    "trades": [
        "ELECTRICAL_CONTRACTOR",
        "PLUMBING_CONTRACTOR",
    ],
    "licenseStatus": "ACTIVE",
    "cities": ["Denver"],
    "zipCodes": [],
    "companyNames": [],
    "licenseNumbers": [],
    "issuedAfter": "",
    "expiresBefore": "",
    "verifyBusinessRecords": True,
    "businessStanding": "ANY",
    "sortBy": "NEWEST_LICENSE",
    "maxResults": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/colorado-contractor-leads").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 '{
  "trades": [
    "ELECTRICAL_CONTRACTOR",
    "PLUMBING_CONTRACTOR"
  ],
  "licenseStatus": "ACTIVE",
  "cities": [
    "Denver"
  ],
  "zipCodes": [],
  "companyNames": [],
  "licenseNumbers": [],
  "issuedAfter": "",
  "expiresBefore": "",
  "verifyBusinessRecords": true,
  "businessStanding": "ANY",
  "sortBy": "NEWEST_LICENSE",
  "maxResults": 10
}' |
apify call muhammadafzal/colorado-contractor-leads --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,muhammadafzal/colorado-contractor-leads"
        }
    }
}
```

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/76ORRF9SgZLgFUE3d/builds/FWwphQePuaiFJBQOz/openapi.json