# Tennessee Contractor License Lookup & Verify (`muhammadafzal/tennessee-contractor-license-lookup`) Actor

Search Tennessee TDCI's public contractor license records by company name, individual name, or license number. Returns official status, expiration, classification, monetary limit, and source detail links.

- **URL**: https://apify.com/muhammadafzal/tennessee-contractor-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 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.
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

## Tennessee Contractor License Lookup & Verify

Search Tennessee's official Department of Commerce and Insurance (TDCI) public registry for **general Contractor** licenses. Search by business name, individual last name, or license number and return the official status, expiration date, classification, monetary limit, public location summary, and direct record link.

The Actor reads the public search at [search.cloud.commerce.tn.gov](https://search.cloud.commerce.tn.gov/). The Tennessee Board for Licensing Contractors links consumers to the public verification tool, which says search results are updated daily. TDCI remains the authoritative source for current licensing decisions.

### What the Actor returns

| Field | Description |
| --- | --- |
| `licenseeName`, `entityType` | Business or individual name and organization/individual type shown by TDCI |
| `licenseNumber`, `licenseType`, `boardProgram` | Official identifier and licensing program |
| `status`, `expirationDate`, `originalLicensureDate` | Source status and dates; expiration uses `YYYY-MM-DD` |
| `appearsActiveAndUnexpired` | Convenience check that the displayed status is Active and the date has not passed as of the source retrieval date |
| `classificationCodes`, `monetaryLimitUsd`, `publicModifiers` | Contractor classifications and monetary limit when the detail record shows them |
| `city`, `state`, `postalCode`, `county` | Public location summary. The source view does not show a street address, phone, or email |
| `sourceRetrievedAt`, `checkedAt` | Portal retrieval time and this Actor's UTC check time |
| `sourceDetailUrl`, `sourceUrl` | Direct official detail record and TDCI search page |
| `sourceResultCount`, `sourcePageRecordCount`, `sourceResultsTruncated` | Portal match count, records rendered on its first page, and whether either the Actor or portal limited output |

The `appearsActiveAndUnexpired` flag is not legal advice or a determination that a contractor may bid on a particular project. TDCI advises users to consider both status and expiration; an Active status with an expired date is not treated as current. Open the official detail link for the latest record and consult TDCI when a licensing decision matters.

### Search scope

This Actor searches the **Contractor** license type under TDCI's **Contractors and Ltd Licensed Plumbers** program. It does not search Home Improvement Contractor, Limited Licensed Electrician, Limited Licensed Plumber, or other professional boards. It reads the first result page only and opens at most `maxResults` detail pages. Broad search terms can match many records; use a distinctive company name or an exact license number for focused verification.

The official portal exposes current search results, not a downloadable contractor directory. It may render fewer first-page records than the total match count. The summary and every output item make truncation visible; run a narrower search or verify further records directly on TDCI's site.

### Input

| Field | Values | Default / limit |
| --- | --- | --- |
| `searchType` | `business_name`, `license_number`, `individual_last_name` | `business_name` |
| `query` | One business name, license number, or last name | `Doe`; 2–100 characters |
| `firstName` | Optional first-name filter for an individual search | Empty |
| `maxResults` | Maximum detail records to open and return | 10; 1–25 |

Example: search a business name.

```json
{
  "searchType": "business_name",
  "query": "Doe",
  "maxResults": 10
}
```

Example: verify a known license number.

```json
{
  "searchType": "license_number",
  "query": "85359",
  "maxResults": 1
}
```

Example: find an individual's contractor license.

```json
{
  "searchType": "individual_last_name",
  "query": "Doe",
  "firstName": "John",
  "maxResults": 5
}
```

### Output example

```json
{
  "licenseeName": "DOE RIVER CONSTRUCTION, INC.",
  "entityType": "Organization",
  "licenseNumber": "85359",
  "licenseType": "Contractor",
  "boardProgram": "Contractors and Ltd Licensed Plumbers",
  "status": "Active",
  "expirationDate": "2028-03-31",
  "originalLicensureDate": "2026-03-19",
  "appearsActiveAndUnexpired": true,
  "classificationCodes": ["BC-A"],
  "monetaryLimitUsd": 125000,
  "city": "BUTLER",
  "state": "Tennessee",
  "postalCode": "37640",
  "county": "Carter",
  "sourceDetailUrl": "https://search.cloud.commerce.tn.gov/search/C2952503/detail",
  "detailAvailable": true
}
```

The record above is an example of the source shape; live values can change. The source detail page may omit classifications, monetary limits, dates, or location components for some records. When the list card is valid but a detail page cannot be read, the Actor preserves the card data, sets unavailable detail fields to `null`, and records the issue in `OUTPUT`.

### Pricing

One run has an automatic start event and each default-dataset record has one automatic result event. There is no second custom charge for the same record. These prices were read back from the live private Actor's PPE configuration; platform usage is not passed through as a separate user charge. The creator still pays the platform usage cost from event revenue.

| Event | FREE | BRONZE | SILVER | GOLD | PLATINUM | DIAMOND |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| Actor start | $0.005 | $0.005 | $0.005 | $0.005 | $0.005 | $0.005 |
| Contractor record | $0.010 | $0.00975 | $0.00950 | $0.008 | $0.008 | $0.008 |

An empty run costs one start event ($0.005 at every tier). A one-record run costs $0.015 FREE, $0.01475 BRONZE, $0.01450 SILVER, or $0.013 GOLD, PLATINUM, and DIAMOND in event charges. A five-record run costs $0.055 FREE, $0.05375 BRONZE, $0.05250 SILVER, or $0.045 GOLD, PLATINUM, and DIAMOND. `maxTotalChargeUsd` has a $0.015 minimum, enough to cover a start plus one FREE-tier record. The Actor's default result cap is 10, and a verified free-plan run delivers at most 5 records.

### Reliability and limits

- The Actor uses the public TDCI search and record-detail screens. It does not log in, solve a CAPTCHA, or bypass access controls.
- Searches are sequential, with one browser and at most 25 detail pages per run. Free-plan runs are capped at five delivered records before each write.
- If TDCI presents a challenge, denies access, or changes its public form, the Actor reports `BLOCKED` or `FAILED` with zero fabricated records.
- If the query is valid but no record matches, the Actor reports `EMPTY` and writes no result record.
- Valid partial records are retained if a detail page fails; unavailable detail fields stay null and the run summary records the warning.
- `OUTPUT` and `SUMMARY` store machine-readable run diagnostics separately from the license-record dataset.

### Legal and data-use note

This Actor is an independent convenience tool, not a Tennessee government service. It processes public professional and business license information. Use it for legitimate license verification, respect TDCI's public search and applicable terms, and avoid high-volume or disruptive searches. Do not use the result as the sole basis for a legal or contracting decision. The official Board page describes its mission and points to the public verification search: [Tennessee Board for Licensing Contractors](https://www.tn.gov/commerce/regboards/contractors.htmlclick.html). TDCI's public search guidance is available from [Contractor Help & Support](https://www.tn.gov/commerce/regboards/contractors/help-support.html).

# Actor input Schema

## `searchType` (type: `string`):

Choose the single TDCI search field to use. Use business name for an organization, license number for an exact verification, or last name for an individual. The official search is limited to the general Contractor license type.

## `query` (type: `string`):

Use the one value matching Search by. Enter a company name or distinctive partial name (for example Doe River), a license number (85359), or an individual's last name (Doe). Avoid very broad terms; the source may return a large first page. Searches use only the official TDCI general Contractor program.

## `firstName` (type: `string`):

Use this only with Search by = individual\_last\_name to narrow an individual's license search. Leave blank when the first name is unknown. Example: John.

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

Use this to cap detail pages opened and records delivered. The Actor reads only the first TDCI result page and returns up to this many records; if the portal has more matches, narrow the query or verify additional records with a separate run. Verified free-plan users are capped at 5 records per run; paid and agentic-paid runs may request 1–25. Default 10.

## Actor input object example

```json
{
  "searchType": "business_name",
  "query": "Doe",
  "firstName": "",
  "maxResults": 10
}
```

# Actor output Schema

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

Schema-validated public general contractor records from Tennessee TDCI.

## `output` (type: `string`):

Outcome class, portal match count, delivered records, result limit, truncation state, 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 = {
    "searchType": "business_name",
    "query": "Doe",
    "maxResults": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("muhammadafzal/tennessee-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 = {
    "searchType": "business_name",
    "query": "Doe",
    "maxResults": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("muhammadafzal/tennessee-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 '{
  "searchType": "business_name",
  "query": "Doe",
  "maxResults": 10
}' |
apify call muhammadafzal/tennessee-contractor-license-lookup --silent --output-dataset

```

## MCP server setup

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