# Contractor License Lookup: Multi-State Official Data (`transparent_meteorite/contractor-license-lookup`) Actor

Search, verify and monitor contractor and trade licenses from official state open data: WA, TX, CT, CO, OR, DE. Status, expiry, trade, address, business phone, OR bonds and insurance. New-license and expiring-soon lists. $2 per 1,000 records.

- **URL**: https://apify.com/transparent_meteorite/contractor-license-lookup.md
- **Developed by:** [Detroit Web Agent - Open Data](https://apify.com/transparent_meteorite) (community)
- **Categories:** Lead generation, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

## Contractor License Lookup - multi-state contractor and trade licenses from official open data ($2 per 1,000)

![Contractor License Lookup: features, price and a real output row](https://api.apify.com/v2/key-value-stores/9BAn0msnxToXlD9TO/records/sf-contractor-license-lookup-banner-10151907.png)

[![Run it free on Apify](https://api.apify.com/v2/key-value-stores/9BAn0msnxToXlD9TO/records/sf-cta.png)](https://console.apify.com/actors/jjkUHgSlwtkjNWEVs/input)

| Price per 1,000 licenses | Free plan | Starter | Scale | Business |
|---|---|---|---|---|
| **This Actor** | **$2.00** | **$2.00** | **$2.00** | **$2.00** |
| Most-used alternative | $2.00 | $2.00 | $2.00 | $2.00 |

<sub>Pay per event, no monthly rental. Prices read from each Actor's public Apify pricing on 2026-10-15; check the Pricing tab for the current figure.</sub>

![Contractor License Lookup sample output table from a real run](https://api.apify.com/v2/key-value-stores/9BAn0msnxToXlD9TO/records/sf-contractor-license-lookup-output-10151907.png)

- **In short:** Contractor License Lookup (Apify actor `transparent_meteorite/contractor-license-lookup`) searches, verifies and monitors contractor and trade licenses from the official open-data portals of Washington, Texas, Connecticut, Colorado, Oregon and Delaware.
- **Who it is for:** lead-generation and sales teams selling to contractors, insurance and surety brokers, building-supply and equipment vendors, marketplaces and property managers that vet contractors, compliance and procurement teams.
- **Input:** mode (search, verify, new_licenses), states, trade, city, ZIP, county, business or person name, license number, active only, contractors only, expiring-soon window, verify list.
- **Output:** one row per license: state, agency, license number, license type, normalized trade, business name, person name, status, issue / effective / expiration dates, isActive, isExpiringSoon, address, city, ZIP, county, business phone where the agency publishes one, source record link, official lookup link, retrieval time.
- **Price:** $0.002 per license record plus $0.00005 per run start. Verify rows that find nothing are free. No subscription.
- **Limits:** six states today, only the fields each agency publishes. California (CSLB), Florida (DBPR) and other states are not covered.

**Key facts**

- Actor name: Contractor License Lookup
- Actor ID: `transparent_meteorite/contractor-license-lookup`
- Data source: official state open-data portals (Socrata APIs) run by state agencies
- Pricing model: pay per event (`apify-actor-start` $0.00005, `license-record` $0.002)
- Output formats: JSON, CSV, Excel, XML, HTML table (Apify dataset)
- Access: Apify Console, REST API, JavaScript and Python clients, schedules, webhooks, Apify MCP server
- Login or third-party API key needed: no, only an Apify account
- Also known as: contractor license search, contractor license verification API, trade license lookup, electrician license lookup, plumber license lookup, roofing contractor leads, new contractor licenses list
- Last updated: 2026-10-13

### Why choose this actor

Most contractor license data is locked behind one-at-a-time lookup pages, a different one for every state and every board. This actor reads the bulk license datasets that the agencies themselves publish on their open-data portals and gives you one clean, consistent table across states.

- **Official sources only.** Every row comes from a dataset published by the licensing agency (Washington L\&I, Texas TDLR, Connecticut DCP, Colorado DORA, Oregon CCB and BCD, Delaware DPR). Each row carries `sourceRecordUrl`, a link to the exact record in the agency's open-data API, so you can check any value yourself.
- **One schema for six states.** Field names, dates (ISO `YYYY-MM-DD`), phone format and trade names are the same no matter which state the row came from.
- **Normalized trades.** State license classes (for example WA specialty code `CD`, CT credential `HIC`, OR BCD `LHR`) are mapped to 28 plain trades such as `roofing`, `electrical`, `plumbing`, `hvac`, `home_improvement`.
- **Honest activity flag.** `isActive` is true only when the agency status is active and the expiration date has not passed. Some records still say "Active" after they expire; this actor does not count those as active.
- **Three jobs in one actor.** Search for leads, verify a list of license numbers or names, or pull licenses issued in the last N days.
- **Polite and dependable.** Requests are serial, at least 350 ms apart, filtered on the server, paged, and retried on rate limits and server errors. No login, no browser, no scraping of lookup pages.

### What it does

Pick a mode:

1. **search** - find licenses that match your filters: states, trade, city, ZIP, county, business name words, person name words, license number, active only, contractor licenses only, expiring soon.
2. **verify** - paste up to 1,000 license numbers or business names. You get exactly one row per input with `found`, `matchType` (`licenseNumber`, `exactName` or `nameContains`), `matchCount`, the best match's full record and up to five other matches. Use a state prefix such as `TX:100733` to narrow an item to one state.
3. **new_licenses** - licenses issued or registered in the last N days (1 to 365), newest first, in the states that publish an issue or registration date.

#### States and datasets covered

| State | Agency | Dataset | What is in it | Refresh (as stated by the portal) |
|---|---|---|---|---|
| WA | Department of Labor & Industries | [data.wa.gov m8qx-ubtq](https://data.wa.gov/d/m8qx-ubtq) | Construction, electrical, plumbing and elevator contractors, all statuses | three times a day |
| TX | Department of Licensing and Regulation | [data.texas.gov 7358-krk7](https://data.texas.gov/d/7358-krk7) | Electricians and electrical contractors, A/C contractors and technicians, appliance installers, well drillers, elevator and sign contractors | updated periodically by TDLR |
| CT | Department of Consumer Protection | [data.ct.gov ngch-56tr](https://data.ct.gov/d/ngch-56tr) | Home improvement, new home, electrical, plumbing, heating, sheet metal, fire protection, elevator, demolition, glazing, pool, well, solar, lead and asbestos credentials | daily |
| CO | Department of Regulatory Agencies | [data.colorado.gov 7s5z-vewr](https://data.colorado.gov/d/7s5z-vewr) | Electrical and plumbing contractors, masters, journeymen, residential wiremen and plumbers | daily |
| OR | Construction Contractors Board | [data.oregon.gov g77e-6bhs](https://data.oregon.gov/d/g77e-6bhs) | Active residential and commercial contractors, with bond and insurance details | daily (active licenses only) |
| OR | Building Codes Division | [data.oregon.gov vhbr-cuaq](https://data.oregon.gov/d/vhbr-cuaq) | Active electrical, plumbing, boiler and elevator licenses | updated periodically by BCD (active licenses only) |
| DE | Division of Professional Regulation | [data.delaware.gov pjnv-eaih](https://data.delaware.gov/d/pjnv-eaih) | Electricians, master plumbers, HVACR, elevator mechanics | daily |

Data is read live at run time, so you always get what the agency published most recently.

**Not covered:** California (CSLB), Florida (DBPR), Arizona, Nevada, North Carolina, Georgia, New York, Michigan and every other state not in the table. Those states either publish no bulk open dataset or publish it only as downloads or lookup pages that this actor does not scrape. Local city and county licenses are not covered.

### Use cases

- **Homeowners and property managers:** confirm a contractor's license is active and not expired before signing a job.
- **General contractors:** verify subcontractor licenses and trades in bulk before onboarding them.
- **Insurers, lenders and marketplaces:** screen contractor applicants against official state records as part of KYB.
- **Lead generation:** pull licensed contractors by trade and city, then schedule a run to catch new or expiring licenses.

### Quick start

1. Open the actor in Apify Console and click **Try for free**.
2. Keep the prefilled input (Washington, trade `roofing`, city `Seattle`, 20 results) and click **Start**. A test run finishes in a few seconds.
3. Open the **Overview** table, or export as CSV, JSON or Excel.

A minimal search input:

```json
{ "mode": "search", "states": ["WA"], "trade": "roofing", "city": "Seattle", "maxResults": 20 }
```

### Output fields

| Field | Meaning |
|---|---|
| `state` | Two-letter state of the licensing agency |
| `source` | Agency name |
| `licenseNumber` | License number exactly as the agency publishes it |
| `licenseType` / `licenseTypeCode` | License class as published (and its short code) |
| `trade` / `trades` | Normalized trade (primary) and all trades the license covers |
| `tradeBasis` | `license` when the trade comes from the license class; `business name` when it was inferred from the business name (Oregon CCB specialty contractors only) |
| `specialties` | Published specialty descriptions (WA, CT) |
| `businessName` / `dbaName` | Licensed business and DBA name where published |
| `personName` | Individual licensee, principal or responsible managing individual |
| `holderType` | `business`, `sole_proprietor` or `individual` |
| `entityType` | Business entity type where published (WA, CT) |
| `isContractorLicense` | True for business or contractor-level licenses, false for journeyman, apprentice and technician licenses |
| `status` | Status as published (Texas publishes none, so it is null there) |
| `isActive` | Status is active and the expiration date has not passed |
| `issueDate` / `effectiveDate` / `expirationDate` | ISO dates where published |
| `daysToExpiration` / `isExpiringSoon` | Days until expiry and whether that is inside your window (default 60 days) |
| `address`, `city`, `addressState`, `zip`, `county` | Address of record as published |
| `phone` | Business phone, only where the agency publishes one as the business contact (WA, TX business phone, OR CCB) |
| `verifyUrl` | Per-record official verification page (Colorado) |
| `officialLookupUrl` | The agency's public license lookup page |
| `sourceRecordUrl` | API link to this record in the official dataset |
| `sourceDataset` | Dataset page on the state portal |
| `sourceId` | Internal source id (for example `OR-CCB`) |
| `details` | Source-specific extras: WA UBI number, OR CCB bonds and insurance, CO renewal date and discipline fields |
| `retrievedAt` | When this run read the record |

Verify mode adds `input`, `found`, `matchType`, `matchCount`, `statesSearched` and `otherMatches`.

### Sample output

Real rows from a local run on 2026-10-13 (input `{"mode":"search","contractorsOnly":true,"maxResults":42}`), shortened to the main columns:

| state | licenseNumber | licenseType | trade | businessName | city | expirationDate | phone |
|---|---|---|---|---|---|---|---|
| WA | 100PLRL754Q5 | CONSTRUCTION CONTRACTOR | general | 100PLUS REMODELING LLC | SEATTLE | 2028-01-13 | 425-229-9790 |
| WA | 100PRPD823OR | CONSTRUCTION CONTRACTOR | carpentry_drywall | 100 PROOF DRYWALL LLC | SOUTHWORTH | 2028-09-19 | 360-317-3229 |
| TX | 1000 | Appliance Installation Contractor | appliance | ABNATION INC | AUSTIN | 2027-03-11 | 281-870-4705 |
| CT | 50.000122 | Lead Abatement Contractor | asbestos_lead | KRONENBERGER & SONS RESTORATION, LLC. | MIDDLETOWN | 2027-07-31 | |
| CO | 100003 | Electrical Contractor | electrical | Headley Electric, LLC | Canon City | 2029-09-30 | |
| OR | 100260 | Residential Specialty Contractor | painting | THE FOXGLOVED PAINTERS & DESIGNERS INC | PORTLAND | 2027-05-14 | 503-255-2327 |
| OR | 10-102PB | PB-Plumbing Contractor | plumbing | JOE PISCOPO PLUMBING LLC | COTTAGE GROVE | 2029-07-01 | |
| DE | HL-0000006 | Master HVACR Restricted | hvac | (person) BRIAN SCHURMAN | Harrington | 2028-10-31 | |

One full record (Oregon CCB, including bond and insurance details):

```json
{
  "state": "OR",
  "source": "Oregon Construction Contractors Board (CCB)",
  "licenseNumber": "100215",
  "licenseType": "Residential General Contractor",
  "licenseTypeCode": "RGC",
  "trade": "general",
  "trades": ["general"],
  "tradeBasis": "license",
  "businessName": "BRUCE HUIE",
  "personName": "BRUCE HUIE",
  "holderType": "business",
  "isContractorLicense": true,
  "status": "ACTIVE",
  "isActive": true,
  "issueDate": "1994-06-20",
  "expirationDate": "2028-02-06",
  "daysToExpiration": 481,
  "isExpiringSoon": false,
  "address": "PO BOX 543",
  "city": "BROOKINGS",
  "addressState": "OR",
  "zip": "97415",
  "county": "Curry",
  "phone": "541-215-0829",
  "officialLookupUrl": "https://search.ccb.state.or.us/search/",
  "sourceRecordUrl": "https://data.oregon.gov/resource/g77e-6bhs.json?license_number=100215",
  "sourceDataset": "https://data.oregon.gov/d/g77e-6bhs",
  "details": {
    "exempt": "Exempt",
    "bonds": [{ "licenseClass": "RGC", "company": "WESTERN SURETY COMPANY", "amount": 25000, "expires": "2028-02-06" }],
    "insuranceCompany": "SCOTTSDALE INSURANCE CO",
    "insuranceAmount": 1000000,
    "insuranceExpires": "2027-08-25"
  }
}
```

A verify row from the same day (input `Sechler Electric Co., Inc.`) came back with `found: true`, `matchType: "exactName"`, Colorado license `100`, `Electrical Contractor`, status `Active`, first issued `1965-07-15`, expiring `2029-09-30`, plus the official `verifyUrl`.

### Input options and examples

| Option | Default | Notes |
|---|---|---|
| `mode` | `search` | `search`, `verify` or `new_licenses` |
| `states` | all six | `WA`, `TX`, `CT`, `CO`, `OR`, `DE` |
| `trade` | none | One of 28 normalized trades. States that cannot express the trade are skipped and listed in the run summary |
| `city`, `zip`, `county` | none | City is an exact, case-insensitive match. ZIP accepts a prefix. County works only in Texas and Oregon |
| `businessName`, `personName` | none | One keyword per line; every word of a keyword must appear (any order) |
| `licenseNumber` | none | Exact number; Colorado also accepts `EC.100836` style |
| `activeOnly` | `true` | Active status and not expired |
| `contractorsOnly` | `false` | Drop journeyman, apprentice and technician licenses |
| `daysBack` | 30 | new_licenses window |
| `expiringWithinDays` | 60 | Window for `isExpiringSoon` |
| `onlyExpiringSoon` | `false` | Keep only licenses expiring inside the window |
| `verifyList`, `verifyBy` | empty, `auto` | Verify mode inputs |
| `maxResults` | 100 | Split fairly across states first, then topped up from states with more matches |

**Electrical contractors in Harris County, Texas:**

```json
{ "states": ["TX"], "trade": "electrical", "county": "Harris", "contractorsOnly": true, "maxResults": 500 }
```

**HVAC licenses expiring in the next 30 days in every state (renewal, bonding and insurance outreach):**

```json
{ "trade": "hvac", "onlyExpiringSoon": true, "expiringWithinDays": 30, "maxResults": 1000 }
```

**New contractor licenses in Connecticut, Colorado and Oregon in the last 7 days:**

```json
{ "mode": "new_licenses", "states": ["CT", "CO", "OR"], "daysBack": 7, "contractorsOnly": true, "maxResults": 500 }
```

**Verify a vendor list:**

```json
{ "mode": "verify", "verifyList": ["WA:04CONCL862CR", "CT:50.000105", "TX:100", "Sechler Electric Co., Inc."] }
```

**Find a contractor by name across all states:**

```json
{ "businessName": ["summit roofing"], "activeOnly": false, "maxResults": 50 }
```

### Pricing

Pay per event, no subscription:

- `apify-actor-start`: $0.00005 per run.
- `license-record`: $0.002 per license record delivered, which is $2 per 1,000 records.

In verify mode only rows that found a license are charged; "not found" rows are free. The actor stops cleanly when your run reaches the maximum cost you set in the run options and says so in the log and status line. Apify's free plan credit is enough for a first test. Apify platform usage is included in the event price.

### How to run

#### Apify Console

Fill the form, click **Start**, then open the Overview table or export the dataset. The run summary (per-state counts, skipped states with the reason, warnings) is saved as the `OUTPUT` record in the key-value store.

#### API

```bash
curl -X POST "https://api.apify.com/v2/acts/transparent_meteorite~contractor-license-lookup/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"states":["WA","OR"],"trade":"roofing","maxResults":100}'
```

JavaScript:

```js
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('transparent_meteorite/contractor-license-lookup').call({ trade: 'plumbing', states: ['CO'], contractorsOnly: true });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

Python:

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("transparent_meteorite/contractor-license-lookup").call(run_input={"mode": "new_licenses", "daysBack": 7})
items = client.dataset(run["defaultDatasetId"]).list_items().items
```

#### Schedule

Create a schedule in Apify Console (for example every Monday at 07:00) with `mode: new_licenses` and `daysBack: 7` to get a weekly list of new licenses, or `onlyExpiringSoon: true` to get a monthly renewal list.

#### n8n, Make, Zapier and MCP

- **n8n:** use the Apify node, operation "Run actor and get dataset", actor `transparent_meteorite/contractor-license-lookup`.
- **Make:** Apify module "Run an Actor", then "Get Dataset Items".
- **Zapier:** Apify app, action "Run Actor", then use the dataset items in the next step (Google Sheets, HubSpot, Slack).
- **AI agents (MCP):** add the Apify MCP server (`https://mcp.apify.com`) with this actor enabled, then ask your assistant, for example, "verify Washington contractor license 04CONCL862CR".

### Limits and honest caveats

- **Six states only.** See the coverage table. If a state is not listed, this actor does not return it.
- **Each state publishes different fields.** Texas publishes no status column, so `status` is null and `isActive` is based on the expiration date. Texas A/C contractor and technician rows carry no address or phone in the dataset. Colorado and Delaware publish city and ZIP but no street. Delaware lists individual licensees only, so business-name searches skip Delaware.
- **Oregon publishes active licenses only.** With `activeOnly: false`, Oregon still returns only active licenses.
- **Washington new_licenses uses the effective date** of the current license term, so renewals appear next to brand-new licenses. Use `effectiveDate` to judge.
- **Texas and Oregon BCD publish no issue date,** so they are skipped in new_licenses mode (the summary says so).
- **Oregon CCB specialty contractors** have no trade in their license class. For trade searches the actor also matches business-name words (for example "ROOF" for roofing) and marks those rows `tradeBasis: "business name"`. Treat them as likely, not certain.
- **Name search is word-based.** Every word of your keyword must appear somewhere in the name. Abbreviations differ by state ("CO" vs "COMPANY").
- **Phone numbers:** only business phones the agency publishes as the license contact. Texas `owner_telephone` and Texas mailing addresses are never output, and no emails are output from any state.
- **Address privacy rule:** for individual non-contractor licenses (journeyman, apprentice, technician) the street line is dropped and only city, state and ZIP are kept, because these are often home addresses. Business and contractor-of-record addresses are returned as published.
- **Freshness depends on the agency.** The actor reads the live dataset at run time; it cannot be fresher than the agency's last update.
- **A dataset is not the legal record.** For a decision that matters (hiring, permitting, payment), confirm on the agency lookup page linked in `officialLookupUrl` or `verifyUrl`.

### Run in 30 seconds

1. Open the Actor in Apify Console and click **Try for free** (or **Start** if you already have an account).
2. Open the **Input** tab, switch to **JSON**, and paste the example below. It is small on purpose, so the first run is quick and cheap.
3. Click **Start**. Most small runs finish in well under two minutes.
4. Open the **Output** tab to read the Overview table, or use **Export** to download JSON, CSV or Excel.

```json
{
  "mode": "search",
  "states": [
    "WA"
  ],
  "trade": "roofing",
  "city": "Seattle",
  "maxResults": 10
}
```

Once the sample looks right, replace the example values with your own list and raise the limits.

### Example API call

Start a search from code or with curl. Replace the placeholder token and username.

```python
from apify_client import ApifyClient

client = ApifyClient("APIFY_TOKEN")
run = client.actor("YOUR_USERNAME/contractor-license-lookup").call(run_input={"mode": "search", "states": ["WA"], "trade": "roofing", "city": "Seattle", "maxResults": 10})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row)
```

```bash
curl -X POST "https://api.apify.com/v2/acts/YOUR_USERNAME~contractor-license-lookup/runs?token=APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "search", "states": ["WA"], "trade": "roofing", "city": "Seattle", "maxResults": 10}'
```

### FAQ

**Is this data legal to use?** These are public records that the agencies publish as open data for reuse. You are responsible for how you use them, including marketing rules such as the TCPA, CAN-SPAM and state telemarketing laws.

**How fresh is it?** As fresh as the agency's dataset. Washington updates three times a day; Connecticut, Colorado, Oregon CCB and Delaware daily; Texas and Oregon BCD periodically.

**Why did a state return nothing?** It was probably skipped because it cannot serve a filter (for example roofing in Texas, county in Washington). The `OUTPUT` record lists every skipped source with the reason.

**Can I get every license in a state?** Yes. Set the state, leave the filters empty and raise `maxResults`. Large pulls are paged 1,000 rows at a time.

**How fast is it?** Searches typically return in seconds to a minute. Verify checks every selected state per item, so it takes a few seconds per item; add a state prefix (`TX:12345`) to make it faster.

**Do you have California or Florida?** Not today. Neither publishes a bulk open dataset that this actor can read.

### Troubleshooting

- **0 results:** remove filters one at a time (city spelling must match the agency's, for example `SEATTLE`), or set `activeOnly` to false.
- **Fewer results than maxResults:** that is everything that matched. Check `perSource` and `filteredOut` in `OUTPUT`.
- **A state shows a warning:** the state portal returned an error after retries. The other states still deliver. Run again later.
- **Verify says not found but the license exists:** the license may be outside the trades this actor covers (for example a Texas barber license), or the name is written differently. Try the license number, or `verifyBy: "name"`.
- **Run stopped early:** you reached the maximum cost per run. Raise it in the run options.

### Terms and responsible use

The data comes from public government datasets. This actor does not log in anywhere, does not bypass any access control and does not scrape lookup pages. It keeps requests serial and spaced out to respect the portals. Use the output lawfully: honor do-not-call and opt-out requests, do not use it to harass or discriminate, and verify a license on the official page before relying on it for a legal or financial decision. This actor is not affiliated with or endorsed by any state agency.

### Changelog

- **0.1 (2026-10-13):** first release. Seven official sources in six states, search, verify and new_licenses modes, 28 normalized trades, expiring-soon flags, Oregon bond and insurance details, Colorado verification links.

### Support

Thanks for trying Contractor License Lookup. If a field is wrong, a state changed its dataset, or you need another state or field, open an issue on the actor's Issues tab with the run URL and we will reply there.

# Actor input Schema

## `mode` (type: `string`):

search: find licenses by trade, location, name or number. verify: one output row per item in the verify list, with found / not found. new_licenses: licenses issued or registered in the last N days (states that publish an issue date).

## `states` (type: `array`):

Which state datasets to query. Empty = all 6 states. Oregon has two sources (CCB construction contractors and BCD electrical, plumbing, boiler and elevator licenses).

## `trade` (type: `string`):

Normalized trade. States whose license types cannot express this trade are skipped (listed in the OUTPUT summary). Leave empty for all trades.

## `city` (type: `string`):

Exact city name as published (case-insensitive), for example Seattle or Austin.

## `zip` (type: `string`):

ZIP or ZIP prefix, for example 98101 or 981.

## `county` (type: `string`):

County name without the word County, for example Harris. Only Texas and Oregon publish county; other states are skipped when this is set.

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

Maximum license records to return across all states (split fairly across states first, then topped up). Ignored in verify mode, which returns one row per input.

## `businessName` (type: `array`):

One keyword per line. A record matches if any keyword matches; within a keyword every word must appear in the business or DBA name. Example: smith roofing.

## `personName` (type: `array`):

One per line. Matches licensee or principal / responsible person names (word order does not matter). Example: john smith.

## `licenseNumber` (type: `string`):

Exact license number, for example 4WALLWD781M5 (WA), HIC.0702746 (CT), 100836 (CO).

## `activeOnly` (type: `boolean`):

Keep only licenses whose status is active AND whose expiration date has not passed.

## `contractorsOnly` (type: `boolean`):

Keep only business / contractor-level licenses and drop individual journeyman, apprentice and technician licenses.

## `daysBack` (type: `integer`):

new_licenses mode: licenses issued in the last N days.

## `expiringWithinDays` (type: `integer`):

isExpiringSoon is true when the license expires within this many days.

## `onlyExpiringSoon` (type: `boolean`):

Keep only licenses that expire within the window above. Useful for renewal, bonding and insurance outreach.

## `verifyList` (type: `array`):

verify mode: one license number or business name per line (max 1000). Prefix with a state to narrow it, for example TX:100733 or WA:4WALLWD781M5.

## `verifyBy` (type: `string`):

Auto treats items with digits and no spaces as license numbers, everything else as names (exact name first, then contains).

## Actor input object example

```json
{
  "mode": "search",
  "states": [
    "WA"
  ],
  "trade": "roofing",
  "city": "Seattle",
  "maxResults": 20,
  "activeOnly": true,
  "contractorsOnly": false,
  "daysBack": 30,
  "expiringWithinDays": 60,
  "onlyExpiringSoon": false,
  "verifyBy": "auto"
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

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

No description

# 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 = {
    "mode": "search",
    "states": [
        "WA"
    ],
    "trade": "roofing",
    "city": "Seattle",
    "maxResults": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("transparent_meteorite/contractor-license-lookup").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 = {
    "mode": "search",
    "states": ["WA"],
    "trade": "roofing",
    "city": "Seattle",
    "maxResults": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("transparent_meteorite/contractor-license-lookup").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 '{
  "mode": "search",
  "states": [
    "WA"
  ],
  "trade": "roofing",
  "city": "Seattle",
  "maxResults": 20
}' |
apify call transparent_meteorite/contractor-license-lookup --silent --output-dataset

```

## MCP server setup

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

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/jjkUHgSlwtkjNWEVs/builds/T6uQho3ZSu5V7CNsT/openapi.json