# California Contractor License Lookup & Search API - CSLB (`captainhandsome/ca-contractor-license-search`) Actor

CSLB lookup for California contractor licences. Search the California State License Board by contractor or business name for licence number, city, classification and licence status - a contractor license API for verification, subcontractor vetting and lead building.

- **URL**: https://apify.com/captainhandsome/ca-contractor-license-search.md
- **Developed by:** [Joseph McRell](https://apify.com/captainhandsome) (community)
- **Categories:** Business, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $12.00 / 1,000 results

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

## California Contractor License Search

Search public California contractor-license results by contractor name and export license numbers, status, city, and name type. The Actor returns a structured default dataset suitable for CSV, JSON, spreadsheets, automations, and AI-agent workflows.

### What data can I extract?

- `contractor_name` - Contractor or business name shown in the CSLB result.
- `name_type` - CSLB classification for the displayed name when present.
- `license_number` - California CSLB contractor-license number.
- `city` - California city displayed for the license record.
- `status` - Current license status displayed by CSLB.

Data source: California Contractors State License Board public search pages.

#### All 21 columns

**Identity** — `bond_number`, `contractor_name`, `license_number`, `name_type`

**Status** — `additional_status`, `classifications`, `license_status_detail`, `status`, `workers_comp_status`

**Dates** — `expire_date`, `issue_date`, `reissue_date`

**Location** — `business_address`, `city`

**Money** — `bond_amount`, `bond_surety`, `bonding_information`

**Contact** — `business_phone`

**Other detail** — `business_entity`, `miscellaneous_information`, `workers_comp_policy`

### Input example

Use a bounded input to control output volume and cost:

```json
{
  "search_terms": [
    "SMITH"
  ],
  "max_items": 10
}
```

`max_items` is a hard ceiling on records returned and billed. The default returns at most 10 records so the Store test and first trial remain inexpensive.

### Output example

Each dataset item is one normalized record. Example values are illustrative:

```json
{
  "contractor_name": "SMITH CONSTRUCTION",
  "name_type": "Business Name",
  "license_number": "123456",
  "city": "Sacramento",
  "status": "Active"
}
```

Download the default dataset as JSON, CSV, Excel, XML, or RSS, or retrieve it through the Apify API.

### Pricing and cost control

This Actor uses Pay Per Event. The built-in `apify-actor-start` event is charged once at run start and `apify-default-dataset-item` is charged once for each dataset item. The live Store pricing panel is authoritative. Set `max_items` to establish a predictable output-charge ceiling; there is no duplicate explicit item charge in the runtime.

### Use with AI agents and MCP

Apify's MCP server can discover this Actor, inspect its strict input and output schemas, call it with `call-actor`, and retrieve structured results with `get-actor-output`.

**Verify California contractors named Smith**

```json
{
  "search_terms": [
    "SMITH"
  ],
  "max_items": 50
}
```

### Common use cases

- Company verification and registry research
- Due-diligence and compliance workflows
- Business-directory enrichment
- Spreadsheet and CRM preparation
- Scheduled public-record monitoring

### Limitations and responsible use

- Public registry data only; this is not an official certificate or legal opinion.
- Source sites can omit fields, change markup, throttle traffic, or be temporarily unavailable.
- Name searches can produce unrelated matches; verify critical records with the originating agency.
- Output coverage is limited to fields displayed by the public result pages.
- The Actor does not bypass authentication, CAPTCHAs, or access controls.

### FAQ

#### Is the output structured?

Yes. Names, identifiers, status, location, and other supported values are separate dataset columns rather than concatenated table-cell blobs.

#### Can I cap cost?

Yes. `max_items` is the hard maximum number of result events and dataset records for a run.

#### Can an AI agent call it?

Yes. The input schema acts as a strict tool contract, and the dataset and Actor output schemas describe every returned field.

#### Is this an official government service?

No. It is an independent extraction tool that reads publicly available registry pages. Confirm consequential decisions at the original source.

### Reliability

The Actor is protected by production canaries, typed output contracts, bounded defaults, and fleet monitoring. If a source-page change causes incomplete output, open an Actor issue with the run ID and a redacted input example.

# Actor input Schema

## `search_terms` (type: `array`):

One or more full or partial contractor or business names to search in California CSLB records.

## `max_items` (type: `integer`):

Hard maximum number of contractor-license records returned and billed.

## `include_details` (type: `boolean`):

Open each licence's CSLB detail page to add issue and expiration dates, business address and phone, classifications, bond number and amount, workers' compensation cover and any administrative actions. Adds one request per record, so runs take longer. Leave off for a fast name-and-status lookup.

## Actor input object example

```json
{
  "search_terms": [
    "SMITH"
  ],
  "max_items": 10,
  "include_details": false
}
```

# Actor output Schema

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

Items from the run's default dataset.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("captainhandsome/ca-contractor-license-search").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("captainhandsome/ca-contractor-license-search").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 '{}' |
apify call captainhandsome/ca-contractor-license-search --silent --output-dataset

```

## MCP server setup

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

```

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/auBYHt5uceIcYQUR8/builds/r24F0HOeLS1q4gKSq/openapi.json