# Massachusetts CSL License Lookup & Verify (`muhammadafzal/massachusetts-construction-license-lookup`) Actor

Look up Massachusetts CSL records by license number or last name. See state-listed status, license type, dates, and limited location fields from the public DOL/OPSI registry.

- **URL**: https://apify.com/muhammadafzal/massachusetts-construction-license-lookup.md
- **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $8.00 / 1,000 verified csl records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## Massachusetts Construction License Lookup & Verify (CSL)

Look up Massachusetts Construction Supervisor License (CSL) records by license number or surname using the public Massachusetts DOL/OPSI verification site. The Actor returns the state-listed license type, status, dates, and selected non-street location fields in a structured dataset.

> Results are informational snapshots from the public verification site. They are not a certified verification letter or a legal determination. Confirm time-sensitive decisions with the state source.

### What the Actor returns

| Field | Description |
|---|---|
| `licenseNumber` | Massachusetts CSL number from the state result |
| `licenseeName` | Licensee name displayed by the source |
| `licenseType` | Construction Supervisor, 1 & 2 Family, or Specialty |
| `licenseStatus` | State status label, preserved as shown |
| `issueDate`, `lastRenewalDate`, `expirationDate` | Detail-page dates normalized to `YYYY-MM-DD` |
| `secondaryLicenseType` | Additional subtype when the state page provides it |
| `doingBusinessAs` | Business name when the detail page provides it |
| `city`, `stateCode`, `zipCode` | Limited license-address location fields; street address and gender are omitted |
| `detailAvailable` | Whether the detail page was read successfully |
| `matchedQuery`, `searchMode` | The input that returned the license |
| `sourceUrl`, `checkedAt` | Source search page and UTC retrieval time |

Run diagnostics and warnings are written to the key-value store record `SUMMARY`. License records remain the only rows in the default dataset.

### Search inputs

Use `queries` with one to ten values. Set `searchMode` to `licenseNumber` or `lastName`. Full license numbers usually give the narrowest result. A last name can match many records, so set `maxResults` to control output and charges.

```json
{
  "queries": ["CS-067262"],
  "searchMode": "licenseNumber",
  "licenseType": "any",
  "licenseStatus": "any",
  "maxResults": 20,
  "includeDetails": true
}
```

To search by surname:

```json
{
  "queries": ["Smith"],
  "searchMode": "lastName",
  "licenseType": "unrestricted",
  "licenseStatus": "Active",
  "maxResults": 10,
  "includeDetails": false
}
```

`licenseType` supports `any`, `unrestricted`, `oneTwoFamily`, and `specialty`. `licenseStatus` can be `any` or a status available in the state form. Search is limited to Massachusetts CSL records; it does not check Home Improvement Contractor registrations or other trades. Free-plan users receive at most five result records per run. Paid-plan runs can return the configured maximum, up to 50.

### Output example

```json
{
  "state": "MA",
  "licenseNumber": "CS-123456",
  "licenseeName": "Example Licensee",
  "licenseType": "Construction Supervisor",
  "licenseStatus": "Active",
  "profession": "Building Licenses",
  "secondaryLicenseType": null,
  "issueDate": "2020-04-15",
  "lastRenewalDate": null,
  "expirationDate": "2028-04-15",
  "doingBusinessAs": null,
  "city": "Boston",
  "stateCode": "MA",
  "zipCode": "02108",
  "detailAvailable": true,
  "searchMode": "licenseNumber",
  "matchedQuery": "CS-123456",
  "sourceName": "Massachusetts DOL/OPSI License Verification Site",
  "sourceUrl": "https://madpl.mylicense.com/Verification/Search.aspx?Facility=N",
  "checkedAt": "2026-09-24T00:00:00.000Z"
}
```

### Pricing

The Actor uses Pay per event pricing: a start event plus the automatic `apify-default-dataset-item` event for each valid dataset record. The Actor does not manually charge synthetic events. Live prices must be verified in Apify before billable runs.

| Tier | Start event | Per CSL record | One-result example |
|---|---:|---:|---:|
| FREE | $0.006250 | $0.010000 | $0.016250 |
| BRONZE | $0.006094 | $0.009750 | $0.015844 |
| SILVER | $0.005938 | $0.009500 | $0.015438 |
| GOLD | $0.005000 | $0.008000 | $0.013000 |
| PLATINUM / DIAMOND | $0.005000 | $0.008000 | $0.013000 |

The prices are set to keep the start event at or above $0.005 across the listed tiers and to include routine direct-source traffic. One result is the minimum useful paid run; a 20-record run costs 20 record events plus one start event. The Actor uses no proxy or external paid API. These are initial prices and should be rechecked against settled cloud usage before publication.

### Reliability and limits

The Actor submits the site's public search form with one sequential request path, follows at most three result pages per search, retries transient errors a bounded number of times, and stops on an access denial or rate limit. It does not bypass sign-in, CAPTCHA, paywalls, or access controls. If the state site denies the request, the run summary reports `BLOCKED` or `PARTIAL`; the Actor does not invent records.

When `includeDetails` is true, the Actor reads the linked detail pages for dates and limited location fields. A failed detail request keeps the valid listing fields and marks `detailAvailable` false. A valid no-match response produces an empty dataset with an `EMPTY` summary. Dataset item billing is handled automatically by Apify when the live synthetic event is enabled; no result is billed when no record is written.

### Source and use

The [Massachusetts Division of Occupational Licensure](https://www.mass.gov/construction-supervisor-licensing) directs users to public license-check portals for CSL verification. The [DOL/OPSI license site](https://madpl.mylicense.com/Verification/Search.aspx?Facility=N) says its search can verify license status and download search results. The state also offers a separate [professional licensing API](https://www.mass.gov/info-details/ma-professional-licensing-api) for approved vendors and municipalities; that API requires an issued key, so this Actor does not call it.

Use the data for routine license screening and follow-up. Do not treat a matching name as identity proof. Recheck the state source before signing contracts, issuing permits, or making other consequential decisions.

# Actor input Schema

## `queries` (type: `array`):

Use one to ten values to search. For licenseNumber mode, enter a CSL number such as CS-067262; full numbers give the narrowest match. For lastName mode, enter a surname such as Smith. This searches CSL records only, not Home Improvement Contractor registrations.

## `searchMode` (type: `string`):

Use licenseNumber for a full or partial Massachusetts CSL number, or lastName for an individual's surname. The lastName mode can return multiple licensees and is bounded by Maximum results.

## `licenseType` (type: `string`):

Use any to check all three Construction Supervisor License types. Choose a specific type to narrow the state search. This does not search other Massachusetts trades or HIC registrations.

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

Use any to include every state-listed status, or select one status to filter the registry results. The Actor reports the source status and does not issue a certified verification letter.

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

Use this to cap returned license records and result-event charges. Default 20; maximum 50. Free-plan runs are capped at 5 records even when a higher value is entered.

## `includeDetails` (type: `boolean`):

Use true to fetch issue, expiration, renewal, licensee name, and city/state/ZIP details from each state result page. Street address and gender are not included. Use false for a faster search with listing fields only.

## Actor input object example

```json
{
  "queries": [
    "CS-067262"
  ],
  "searchMode": "licenseNumber",
  "licenseType": "any",
  "licenseStatus": "any",
  "maxResults": 20,
  "includeDetails": true
}
```

# Actor output Schema

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

Schema-validated CSL records returned by the Massachusetts DOL/OPSI public verification site.

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

Outcome, record counts, query progress, source requests, 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 = {
    "queries": [
        "CS-067262"
    ],
    "searchMode": "licenseNumber",
    "licenseType": "any",
    "licenseStatus": "any",
    "maxResults": 20,
    "includeDetails": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/massachusetts-construction-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 = {
    "queries": ["CS-067262"],
    "searchMode": "licenseNumber",
    "licenseType": "any",
    "licenseStatus": "any",
    "maxResults": 20,
    "includeDetails": True,
}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/massachusetts-construction-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 '{
  "queries": [
    "CS-067262"
  ],
  "searchMode": "licenseNumber",
  "licenseType": "any",
  "licenseStatus": "any",
  "maxResults": 20,
  "includeDetails": true
}' |
apify call muhammadafzal/massachusetts-construction-license-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,muhammadafzal/massachusetts-construction-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/8ajcyV2pRM9MQbpMS/builds/c4t9qGG1hJrUfZDzc/openapi.json