# California CSLB Contractor License Scraper (`muhammadafzal/cslb-california-scraper`) Actor Scrape California Contractors State License Board (CSLB) public records. Search by license number, business name, personnel name, or ZIP/city. Returns full license details: status, classifications, bonds, workers comp, disciplinary actions, personnel, address, phone. - **URL**: https://apify.com/muhammadafzal/cslb-california-scraper.md - **Developed by:** [Muhammad Afzal](https://apify.com/muhammadafzal) (community) - **Categories:** Lead generation, Automation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $25.00 / 1,000 license records 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 CSLB Contractor License Scraper Scrape the California Contractors State License Board (CSLB) public database for full contractor license records. Search by license number, business name, personnel name, or ZIP code — get status, all classifications, bonds, workers' comp, disciplinary actions, personnel, and full contact details in structured JSON. ### Use cases - **Contractor verification** — confirm a contractor is licensed and in good standing before hiring - **Compliance monitoring** — detect newly expired, suspended, or revoked licenses for vendor lists on recurring schedules - **Lead generation** — build targeted lists of licensed contractors by ZIP code, city, classification, or active status - **Subcontractor sourcing** — find qualified subcontractors by specialty classification and region - **Insurance underwriting** — score contractors using disciplinary actions, bond cancellation history, and workers' comp status - **Due diligence** — check complaint and legal action history before signing contracts - **Market research** — analyze contractor density by county/classification, track new-license issuance trends ### Input The actor supports four search modes. Use any one or combine multiple: | Field | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | `licenseNumbers` | array | no | `[]` | Direct license-number lookup (fastest). Example: `["1000001", "812345"]` | | `businessName` | string | no | `""` | Full or partial business name. Example: `"Smith Construction"` | | `personnelLastName` | string | no | `""` | Last name of license-holding individual | | `personnelFirstName` | string | no | `""` | Optional first name to narrow personnel search | | `zipCodes` | array | no | `[]` | California ZIP codes for region-based search. Example: `["92101", "90012"]` | | `city` | string | no | `""` | Client-side filter on business address city | | `classification` | string | no | `""` | Filter by CSLB classification code (e.g. `"C-10"`, `"B"`) | | `status` | select | no | `"any"` | Filter by license status: `any`, `active`, `expired`, `suspended`, `revoked`, `canceled`, `inactive` | | `maxResults` | integer | no | `100` | Hard cap on records returned | | `customProxyUrl` | string | no | `""` | Premium residential proxy URL for maximum reliability | | `proxyConfiguration` | object | no | residential | Apify proxy settings | **At least one search mode is required.** #### Example inputs **License number lookup:** ```json { "licenseNumbers": ["842951", "1000001"], "maxResults": 2 } ```` **Business name search:** ```json { "businessName": "Pacific Construction", "status": "active", "maxResults": 50 } ``` **ZIP code lead generation:** ```json { "zipCodes": ["92101", "92102"], "classification": "C-20", "status": "active", "maxResults": 200 } ``` **Personnel name search:** ```json { "personnelLastName": "Smith", "personnelFirstName": "John", "maxResults": 25 } ``` ### Output Each record contains the full public record for one contractor license: | Field | Type | Description | |-------|------|-------------| | `license_number` | string | CSLB license number | | `business_name` | string | Legal business name | | `license_status` | string | Active, Expired, Suspended, Revoked, Canceled, or Inactive | | `entity_type` | string|null | CORPORATION, LLC, SOLE OWNER, etc. | | `issue_date` | string|null | Original license issue date (ISO 8601) | | `expiration_date` | string|null | License expiration date (ISO 8601) | | `business_address` | string|null | Full street address | | `city` | string|null | Business address city | | `county` | string|null | California county (derived from ZIP) | | `zip_code` | string|null | Business address ZIP | | `business_phone` | string|null | Business phone number | | `classifications` | array | All license classifications `[{code, description}]` | | `bonds` | array | All bonds: contractor's bond, qualifier bond `[{type, company, amount_usd, bond_number, effective_date, cancellation_date}]` | | `workers_comp` | object|null | Workers' comp carrier, policy, dates, or exempt status | | `qualifiers` | array | Qualifying individuals `[{name, association}]` | | `personnel` | array | All listed personnel `[{name, classification, license_number, status}]` | | `disciplinary_actions` | array | Disciplinary actions `[{date, type, summary}]` | | `administrative_actions` | array | Administrative actions `[{date, type, summary}]` | | `detail_url` | string | Direct CSLB detail page link | | `scraped_at` | string | ISO 8601 timestamp | | `source_url` | string | Source page URL | ### Pricing | Event | Price | |-------|-------| | Actor Start | $0.00005 | | License Record | $0.025 per record | You only pay for records successfully scraped. Start with a small `maxResults` to test before scaling. ### Technical notes - **Residential proxy required**: CSLB's F5 BIG-IP WAF blocklists datacenter IPs. The actor uses Apify residential proxy by default. For production bulk runs, provide a premium residential proxy via `customProxyUrl` (Decodo/Bright Data/IPRoyal) for maximum reliability. - **Scheduled downtime**: The CSLB database is unavailable Sundays 8 PM through Monday 6 AM Pacific Time. Avoid scheduling runs during this window. - **Search limits**: Business name searches return up to 50 names per page (pagination handled automatically). Personnel name searches return up to 100 names per page. - **Classification codes**: See the [CSLB classification list](https://www.cslb.ca.gov/About_Us/Library/Licensing_Classifications/) for all 40+ specialty codes. ### Integration Export scraped data, run the scraper via API, schedule and monitor runs, or integrate with other tools. The output dataset is compatible with: - CSV/JSON/Excel export from Apify Console - Zapier and Make webhooks - Direct API access via Apify REST API - CRM import (HubSpot, Salesforce) with field mapping - AI agent tool calls via Apify MCP server # Actor input Schema ## `licenseNumbers` (type: `array`): Look up specific CSLB license numbers (e.g. '1000001', '812345'). Fastest search method — direct single-record lookup, no pagination. Use this field when the user provides exact license numbers or a list of licenses to verify. Do NOT use this when the user describes a trade, region, or company name — use businessName, personnelLastName, or zipCodes instead. ## `businessName` (type: `string`): Full or partial contractor business name. CSLB matches case-insensitively against the legal business name AND associated personnel/owner names — so 'Smith' returns both 'Smith Construction Co' (business) and 'Johnie Cement Work' (owned by John Smith). Use this when the user gives a company name. Returns up to 50 names per search; pagination is handled automatically. Do NOT use this for license-number lookups — use licenseNumbers instead. ## `personnelLastName` (type: `string`): Last name of an individual on a contractor license (owner, officer, or qualifier). Use this field together with personnelFirstName to search by person. Returns up to 100 names per search; pagination is handled automatically. Use this when the user provides a person's name rather than a company name. Do NOT use this for business-name searches — use businessName instead. ## `personnelFirstName` (type: `string`): Optional first name to narrow a personnel-name search. Only applies when personnelLastName is set. Leave blank to search by last name only (returns more results). ## `zipCodes` (type: `array`): List of 5-digit California ZIP codes (e.g. '92101', '90012') to find licensed contractors in each area. Use this when the user wants contractors by region or for building territory-based lead lists. The CSLB ZIP search returns contractors registered in that ZIP. Combine with classification and status filters to narrow results. Do NOT use this for a single license lookup — use licenseNumbers instead. ## `city` (type: `string`): Filter results to a specific California city (e.g. 'San Diego', 'Los Angeles'). Applied as a client-side filter on the business address city. Use this to narrow ZIP-code or business-name searches to one city. Not a standalone search mode — combine with zipCodes or businessName. ## `classification` (type: `string`): Filter results to a specific CSLB classification code. Common codes: 'A' (General Engineering), 'B' (General Building), 'C-10' (Electrical), 'C-36' (Plumbing), 'C-20' (HVAC), 'C-33' (Painting), 'C-39' (Roofing), 'C-27' (Landscaping). Leave blank for all classifications. See cslb.ca.gov for the full classification list. ## `status` (type: `string`): Filter results by current license status. 'Active' is the common choice for lead-generation and insurance use cases. 'Any' returns all records regardless of status. ## `maxResults` (type: `integer`): Hard cap on records pushed to the dataset. Protects against accidental large runs — billing is per record pushed. Start low (10-50) to validate output quality before scaling up. Free users are limited to 100 results; paid users can request up to 1,000,000. ## `customProxyUrl` (type: `string`): Optional premium residential proxy URL (e.g. 'http://user:pass@proxy.decodo.com:10000'). CSLB's edge (F5 BIG-IP) blocklists Apify's shared datacenter IPs and may throttle shared residential. For production runs, provide your own premium residential proxy (Decodo/Bright Data/IPRoyal) for maximum reliability. If left blank, the actor uses Apify residential proxy automatically. ## `proxyConfiguration` (type: `object`): Apify proxy settings. Residential proxy is recommended — CSLB's F5 BIG-IP WAF blocklists datacenter IP pools, causing the search to silently return the empty form instead of results. Residential adds a fraction of a cent per record in proxy traffic, well within billing margin. ## Actor input object example ```json { "licenseNumbers": [], "businessName": "Smith Construction", "zipCodes": [], "status": "any", "maxResults": 10, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `results` (type: `string`): Link to the dataset containing all extracted CSLB contractor records. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "licenseNumbers": [], "businessName": "Smith Construction", "personnelLastName": "", "personnelFirstName": "", "zipCodes": [], "city": "", "classification": "", "status": "any", "maxResults": 10, "customProxyUrl": "", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("muhammadafzal/cslb-california-scraper").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "licenseNumbers": [], "businessName": "Smith Construction", "personnelLastName": "", "personnelFirstName": "", "zipCodes": [], "city": "", "classification": "", "status": "any", "maxResults": 10, "customProxyUrl": "", "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("muhammadafzal/cslb-california-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "licenseNumbers": [], "businessName": "Smith Construction", "personnelLastName": "", "personnelFirstName": "", "zipCodes": [], "city": "", "classification": "", "status": "any", "maxResults": 10, "customProxyUrl": "", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call muhammadafzal/cslb-california-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=muhammadafzal/cslb-california-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "California CSLB Contractor License Scraper", "description": "Scrape California Contractors State License Board (CSLB) public records. Search by license number, business name, personnel name, or ZIP/city. Returns full license details: status, classifications, bonds, workers comp, disciplinary actions, personnel, address, phone.", "version": "1.0", "x-build-id": "TZcblSdWa4ee2ob3X" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/muhammadafzal~cslb-california-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-muhammadafzal-cslb-california-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/muhammadafzal~cslb-california-scraper/runs": { "post": { "operationId": "runs-sync-muhammadafzal-cslb-california-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/muhammadafzal~cslb-california-scraper/run-sync": { "post": { "operationId": "run-sync-muhammadafzal-cslb-california-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "licenseNumbers": { "title": "License Numbers", "type": "array", "description": "Look up specific CSLB license numbers (e.g. '1000001', '812345'). Fastest search method — direct single-record lookup, no pagination. Use this field when the user provides exact license numbers or a list of licenses to verify. Do NOT use this when the user describes a trade, region, or company name — use businessName, personnelLastName, or zipCodes instead.", "items": { "type": "string" }, "default": [] }, "businessName": { "title": "Business / Owner Name", "type": "string", "description": "Full or partial contractor business name. CSLB matches case-insensitively against the legal business name AND associated personnel/owner names — so 'Smith' returns both 'Smith Construction Co' (business) and 'Johnie Cement Work' (owned by John Smith). Use this when the user gives a company name. Returns up to 50 names per search; pagination is handled automatically. Do NOT use this for license-number lookups — use licenseNumbers instead." }, "personnelLastName": { "title": "Personnel Last Name", "type": "string", "description": "Last name of an individual on a contractor license (owner, officer, or qualifier). Use this field together with personnelFirstName to search by person. Returns up to 100 names per search; pagination is handled automatically. Use this when the user provides a person's name rather than a company name. Do NOT use this for business-name searches — use businessName instead." }, "personnelFirstName": { "title": "Personnel First Name", "type": "string", "description": "Optional first name to narrow a personnel-name search. Only applies when personnelLastName is set. Leave blank to search by last name only (returns more results)." }, "zipCodes": { "title": "ZIP Codes", "type": "array", "description": "List of 5-digit California ZIP codes (e.g. '92101', '90012') to find licensed contractors in each area. Use this when the user wants contractors by region or for building territory-based lead lists. The CSLB ZIP search returns contractors registered in that ZIP. Combine with classification and status filters to narrow results. Do NOT use this for a single license lookup — use licenseNumbers instead.", "items": { "type": "string" }, "default": [] }, "city": { "title": "City", "type": "string", "description": "Filter results to a specific California city (e.g. 'San Diego', 'Los Angeles'). Applied as a client-side filter on the business address city. Use this to narrow ZIP-code or business-name searches to one city. Not a standalone search mode — combine with zipCodes or businessName." }, "classification": { "title": "License Classification", "type": "string", "description": "Filter results to a specific CSLB classification code. Common codes: 'A' (General Engineering), 'B' (General Building), 'C-10' (Electrical), 'C-36' (Plumbing), 'C-20' (HVAC), 'C-33' (Painting), 'C-39' (Roofing), 'C-27' (Landscaping). Leave blank for all classifications. See cslb.ca.gov for the full classification list." }, "status": { "title": "License Status", "enum": [ "any", "active", "expired", "suspended", "revoked", "canceled", "inactive" ], "type": "string", "description": "Filter results by current license status. 'Active' is the common choice for lead-generation and insurance use cases. 'Any' returns all records regardless of status.", "default": "any" }, "maxResults": { "title": "Max Results", "minimum": 1, "maximum": 1000000, "type": "integer", "description": "Hard cap on records pushed to the dataset. Protects against accidental large runs — billing is per record pushed. Start low (10-50) to validate output quality before scaling up. Free users are limited to 100 results; paid users can request up to 1,000,000.", "default": 100 }, "customProxyUrl": { "title": "Custom Proxy URL", "type": "string", "description": "Optional premium residential proxy URL (e.g. 'http://user:pass@proxy.decodo.com:10000'). CSLB's edge (F5 BIG-IP) blocklists Apify's shared datacenter IPs and may throttle shared residential. For production runs, provide your own premium residential proxy (Decodo/Bright Data/IPRoyal) for maximum reliability. If left blank, the actor uses Apify residential proxy automatically." }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Apify proxy settings. Residential proxy is recommended — CSLB's F5 BIG-IP WAF blocklists datacenter IP pools, causing the search to silently return the empty form instead of results. Residential adds a fraction of a cent per record in proxy traffic, well within billing margin." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```