# Connecticut Home Improvement Contractor License Verification (`automation-lab/connecticut-hic-license-verification`) Actor

Verify Connecticut home improvement contractor registrations by company name or HIC number. Export official snapshot identity, raw status/reason, expiry, city, refresh dates and query match evidence for vendor review.

- **URL**: https://apify.com/automation-lab/connecticut-hic-license-verification.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.55 / 1,000 hic registrations

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

## Connecticut Home Improvement Contractor License Verification

Look up Connecticut home improvement contractor licenses by company name or HIC registration number. Export official snapshot identity, raw status and reason, expiration, city, source refresh date and query-match evidence for recurring vendor review.

This Actor reads the Connecticut Open Data copy of the state credential register. It is not a legal eligibility decision, live eLicense session or certification of a contractor's fitness. Confirm significant decisions on the official verification service.

### Who is it for?

- Procurement teams reviewing home-improvement vendors before onboarding.
- Property managers refreshing a known contractor's registration details.
- Compliance analysts comparing the same HIC number across scheduled snapshots.

### Why use this Actor?

Keep registration identity, source status and match provenance in one structured record. Exact-number checks avoid treating a loosely similar company name as a verified identity. Name searches return candidates for human review, not an asserted exact company match.

The Actor is deliberately limited to **HOME IMPROVEMENT CONTRACTOR** credentials with the **HIC** type. It does not mix in nursing, electrical, plumbing, salesperson or general business-registration records from the shared source dataset.

### Getting started

1. Enter a company-name fragment, such as `ARETE CONSTRUCTION`, or an HIC number such as `HIC.0631057`.
2. Supply exactly one search field, not both.
3. Set `maxItems` to your desired cap on unique registrations.
4. Run the Actor and inspect the default dataset and `SUMMARY` output.
5. Review candidate identity and freshness before relying on the result.

Example name input:

```json
{"companyName":"ARETE CONSTRUCTION","maxItems":100}
```

Example exact-number input:

```json
{"licenseNumber":"HIC.0631057","maxItems":100}
```

### Input parameters

| Field | Meaning |
| --- | --- |
| `companyName` | Literal case-insensitive substring in published holder name, business name or DBA; matching ANY of those fields qualifies. At least two characters, at most 150. |
| `licenseNumber` | Exact numeric credential-number match for digits or `HIC.` plus digits. Prefix case and leading zeros are normalized. A published code with an alphanumeric suffix, such as `HIC.0516257.2025`, instead matches the complete code exactly, preserving zeros and suffix. |
| `maxItems` | Run-wide unique-record cap, default 100, range 1–10000. Zero and unlimited are unsupported. |

Leading and trailing query whitespace is trimmed. Internal whitespace is preserved. Name matching is not whole-word, fuzzy, phonetic or exact whole-field equality. Percent and underscore characters are literal substrings, not wildcard operators. An empty input, unsupported field, malformed number or conflicting search fields fails validation.

### Connecticut home improvement contractor licenses output

| Field | Meaning |
| --- | --- |
| `credentialId` | Stable source identifier, used to deduplicate within a run. |
| `companyName`, `businessName`, `dba`, `holderType` | Published identity and entity type. The holder can be an individual; the field name is not proof of incorporation. |
| `licenseNumber`, `credentialNumber` | Full published HIC code and numeric source number. |
| `credentialDescription` | Always the HIC home-improvement-contractor class. |
| `status`, `statusReason`, `isActive` | Raw source status/reason and converted source active flag. |
| `expirationDate`, `issueDate` | Source timestamps, without an invented timezone. |
| `city`, `state` | Published holder location; address state can be outside Connecticut. |
| `sourceRefreshedAt` | Source record refresh timestamp, not retrieval time. |
| `sourceDatasetUrl`, `verificationUrl` | Official dataset and manual search attribution links. |
| `query`, `matchBasis`, `scrapedAt` | Normalized query, exact-number versus name-substring provenance, and UTC retrieval time. |

Missing optional values are `null`. No phone, email, insurance, bond, complaint history, disciplinary interpretation or contact enrichment is supplied.

### Output example

A real public registration returned during a name lookup (retrieval timestamp shortened to an illustrative value):

```json
{
  "credentialId":"1001126",
  "companyName":"ARETE CONSTRUCTION LLC",
  "businessName":"ARETE CONSTRUCTION LLC",
  "dba":null,
  "holderType":"LIMITED LIABILITY COMPANY",
  "licenseNumber":"HIC.0631057",
  "credentialNumber":"631057",
  "credentialDescription":"HOME IMPROVEMENT CONTRACTOR",
  "status":"ACTIVE",
  "statusReason":"CURRENT",
  "isActive":true,
  "expirationDate":"2027-03-31T00:00:00.000",
  "issueDate":"2011-06-07T00:00:00.000",
  "city":"Monroe",
  "state":"CT",
  "sourceRefreshedAt":"2026-02-19T00:00:00.000",
  "sourceDatasetUrl":"https://data.ct.gov/Business/State-Licenses-and-Credentials/ngch-56tr",
  "verificationUrl":"https://www.elicense.ct.gov/Lookup/LicenseLookup.aspx",
  "query":{"companyName":"ARETE CONSTRUCTION"},
  "matchBasis":"company-name-substring",
  "scrapedAt":"2026-10-08T14:00:00.000Z"
}
```

### Completeness and no-result behavior

The `SUMMARY` key in the default key-value store records saved/observed counts, duplicate counts, query, status and completeness:

- `snapshot-exhausted`: a short page ended the available snapshot search.
- `max-items-reached`: the output cap was reached; more records may exist.
- **charge-budget-reached**: the SDK's limit prevented saving all accepted records.
- `partial-or-unknown`: the run failed; any saved rows are partial results.

Records are ordered by source credential ID and deduplicated within this run. The Actor does not preserve a cross-run cache or compare historical state. Offset pagination reflects the source at request time and is not a transactionally frozen snapshot. Source changes during a long search can affect coverage.

An exhausted search with zero rows is a valid empty result. It does **not** establish that a vendor is unlicensed, revoked or ineligible. Try the complete HIC number and then check eLicense manually.

### How much does it cost to verify Connecticut HIC registrations?

The billing contract has a one-time `start` event and one `item` event per unique registration saved. Rejected, duplicate and absent records have no registration-item charge. A valid empty lookup still has the start charge. Invalid input is rejected before explicit Actor charges.

The start fee is **$0.001 per run**. Each saved HIC registration costs $0.0029716 on FREE, $0.002584 on BRONZE, $0.0020155 on SILVER, and $0.0015504 on GOLD, PLATINUM or DIAMOND. For example, BRONZE event charges total $0.003584 for one registration, $0.02684 for ten, or $0.2594 for one hundred, including the start fee.

Consult the Actor's live pricing panel for the current plan-tier rates before running. Your spending ceiling can stop collection early; inspect the completeness summary rather than assuming the requested record cap was fulfilled. Platform compute/storage charges, where applicable to your Apify plan, are separate from the Actor's event tariff.

### Integrations

Export the default dataset as JSON or CSV from Apify to a spreadsheet, data warehouse or compliance pipeline. Join repeated exact-number results on `credentialId` or `licenseNumber`, retaining both `sourceRefreshedAt` and `scrapedAt` so a newly retrieved but unchanged snapshot is not mistaken for a new registration update.

Use Apify schedules to repeat a saved input and implement field comparisons downstream. This Actor itself does not send alerts, store prior runs, manage a watchlist or write to Notion. It does not accept a batch of separate company queries in one run.

### API usage

After deployment, start a single run with an authorized Apify token:

```bash
curl -X POST 'https://api.apify.com/v2/acts/automation-lab~connecticut-hic-license-verification/runs' \
  -H "Authorization: Bearer $APIFY_TOKEN" -H 'Content-Type: application/json' \
  -d '{"licenseNumber":"HIC.0631057","maxItems":100}'
```

The returned run ID is not the result data. Follow that same run to a terminal status and read its `defaultDatasetId`; do not start another run merely to poll.

JavaScript with `apify-client`:

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/connecticut-hic-license-verification')
  .call({ licenseNumber: 'HIC.0631057', maxItems: 100 });
if (run.status !== 'SUCCEEDED') throw new Error(`Lookup ${run.id}: ${run.status}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems({ limit: 100 });
console.log(items);
```

Python with `apify-client`:

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/connecticut-hic-license-verification').call(
    run_input={'licenseNumber': 'HIC.0631057', 'maxItems': 100})
if run['status'] != 'SUCCEEDED':
    raise RuntimeError(f"Lookup {run['id']}: {run['status']}")
print(client.dataset(run['defaultDatasetId']).list_items(limit=100).items)
```

### MCP usage

Configure a stable Actor-specific tool subset:

```bash
claude mcp add --transport http apify \
  'https://mcp.apify.com?tools=automation-lab/connecticut-hic-license-verification'
```

Equivalent configuration for Claude Desktop, Cursor, and VS Code:

```json
{"mcpServers":{"apify":{"url":"https://mcp.apify.com?tools=automation-lab/connecticut-hic-license-verification"}}}
```

Authenticate as required by your client. Example prompt: “Look up HIC.0631057, show the raw status and source refresh date, and explain the match evidence without making a legal qualification decision.”

Discover actual names and argument schemas with scoped `tools/list`. Actor selection also exposes run/dataset/KV/abort helpers, not exactly one tool; discovery alone does not authorize execution or aborting. For an authorized call, start once and retain the run/storage IDs. `call-actor` waits at most 0–45 seconds (`waitSecs`, default 30). If still running, follow that same run with bounded 2/4/8-second backoff capped at 10 seconds and a total deadline such as 120 seconds. Set client request timeout above the selected wait plus transport margin. On timeout, recover the known run; if its ID is unknown, report uncertainty rather than blindly rerunning. At deadline, report pending with the ID and stop polling.

After success, read bounded untransformed JSON pages using `get-dataset-items`, the returned dataset ID, explicit `offset`, `limit` and needed `fields`. A consumer can use 20-row pages, at most 100 source rows and 64 KiB of serialized UTF-8 results admitted to model context, whichever comes first. Enforce byte limits host-side, including oversized rows/pages; disclose omissions or summaries. If the client cannot intercept oversized results, do not claim a hard byte guarantee. Track source offsets, report truncation and continuation offset, and keep full exports outside model context. Terminal failures and any available rows must be reported as partial, not successful complete results. These consumer context budgets do not change the Actor's collection contract. No universal token-savings claim is made: client discovery/cache behavior varies.

### Freshness, limits and troubleshooting

The upstream dataset may lag eLicense and source refresh dates can differ across records. An ACTIVE flag or future expiration is raw evidence, not an assurance that all regulatory conditions are satisfied.

Transient network errors, HTTP 429 and HTTP 5xx receive up to three attempts per page with bounded backoff. Each request including response reading has a 20-second deadline. Permanent HTTP errors and malformed/out-of-scope payloads fail rather than masquerading as empty data. No browser, login or paid proxy fallback is enabled.

If a name returns too many candidates, use the exact registration number. If the official API is unavailable, retry later or verify manually; the Actor does not silently substitute another profession or unofficial source. HIC-number searches cannot be used for nursing or other trade credentials.

### Legality, responsible use and privacy

Use public registration information for proportionate, lawful vendor review. Respect source terms, applicable privacy rules and retention requirements. Do not infer personal contact details or use ambiguous name candidates as automatic adverse decisions.

Failed operations send sanitized diagnostic input, exceptions and Actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL queries are removed, and reports are retained for 30 days.

The Actor does not use AI for lookup or output. Its only runtime data recipients are the official Connecticut Open Data source (your search query), Apify (run storage and logs), and our private GlitchTip service (sanitized failures). No external contact-enrichment or paid proxy dependency is enabled. Dataset/KV/log retention follows your Apify account and platform settings; the Actor does not delete your saved exports automatically or keep a separate result cache. Remove stored runs/datasets through your Apify account when no longer needed. For product help, use the Actor's Store Issues tab. This is an independent tool, not affiliated with or endorsed by Connecticut government or Apify.

### Frequently asked questions

**Is this a real-time eLicense check?** No. It queries the official Open Data snapshot and supplies a manual eLicense search link, not a record-specific detail URL.

**Can I search multiple companies at once?** No. One run accepts exactly one name or number. Run separate saved inputs or orchestrate them downstream.

**Why did a name match the wrong company?** Substring candidates are not exact identity assertions. Inspect holder/business/DBA names and use the known HIC number for stronger evidence.

**Does an empty result mean the contractor is unlicensed?** No. Coverage/freshness, spelling and input identity may affect a lookup. Check the official verification service.

**Are expired registrations included?** Yes. No ACTIVE-only filter is silently applied; raw status and reason are preserved.

### Related Actors

[Connecticut Business Registry Scraper](https://apify.com/automation-lab/connecticut-sots-concord-business-search) can support separate entity-registration review. Corporate registration is not an HIC registration and should not replace contractor verification.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/connecticut-hic-license-verification/changelog.md

# Actor input Schema

## `companyName` (type: `string`):

Case-insensitive literal substring in published holder name, business name or DBA (ANY of these fields). Leading/trailing query whitespace is trimmed; internal whitespace is preserved. Use at least two characters. Cannot be combined with licenseNumber.

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

Exact numeric credential-number match for digits (631057) or HIC.0631057; prefix case and leading zeros are normalized. If a published code has a suffix (HIC.0516257.2025), the complete code matches exactly, preserving zeros and suffix. Only HOME IMPROVEMENT CONTRACTOR/HIC records are included. Cannot be combined with companyName.

## `maxItems` (type: `integer`):

Run-wide cap on unique credential IDs saved, from 1 to 10000; default 100. Zero/unlimited is unsupported. Ordered source pages stop at this cap or charge budget. SUMMARY distinguishes truncated results from snapshot exhaustion; a capped search is not a complete roster.

## Actor input object example

```json
{
  "companyName": "ARETE CONSTRUCTION",
  "maxItems": 10
}
```

# Actor output Schema

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

Unique source registration rows.

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

Saved counts, query and snapshot completeness.

# 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 = {
    "companyName": "ARETE CONSTRUCTION",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/connecticut-hic-license-verification").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 = {
    "companyName": "ARETE CONSTRUCTION",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/connecticut-hic-license-verification").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 '{
  "companyName": "ARETE CONSTRUCTION",
  "maxItems": 10
}' |
apify call automation-lab/connecticut-hic-license-verification --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/connecticut-hic-license-verification"
        }
    }
}
```

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/bRvJoXEte6Yjvi9IP/builds/XelRE9iGGSlFEDqaD/openapi.json