# Contractor License Verification Scraper (`automation-lab/contractor-license-verification-scraper`) Actor Verify contractor licenses from official public state lookup pages. Export status, expiration, license type, source URL, and public contact fields. - **URL**: https://apify.com/automation-lab/contractor-license-verification-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Other - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.02 / 1,000 item extracteds 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/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 ## Contractor License Verification Scraper Verify contractor and trade license records from official public state lookup systems and turn repetitive compliance checks into a structured Apify dataset. This actor is built for vendor onboarding, marketplace trust and safety, property-management screening, lead enrichment, insurance review, and any workflow where teams need evidence from public contractor license databases instead of manual copy-paste checks. ### Overview Contractor License Verification Scraper searches supported public government license lookup pages and normalizes the results into one dataset. The first production sources are Texas TDLR and California CSLB public search pages. Use it when you need to confirm license status, capture license numbers, monitor expiration dates, enrich contractor leads, or create an audit trail for vendor due diligence. ### What this actor does - Searches contractor or licensee names in public state databases. - Verifies known license numbers when the source supports direct lookup. - Captures status, license type, expiration date, source agency, and public contact/location fields. - Keeps the official source URL with every record so reviewers can open the original page. - Adds `scrapedAt` timestamps for auditability. - Saves all records in a typed dataset ready for CSV, Excel, JSON, Google Sheets, or API export. ### Supported official license sources The actor starts with high-value public contractor license sources that are reachable without login: - Texas Department of Licensing and Regulation (TDLR) - California Contractors State License Board (CSLB) Texas TDLR is the primary high-volume source. California CSLB is supported through its public search flow and can return public license-number records for matching names. ### Who is it for This scraper is useful for: - Compliance teams checking vendor license status. - Marketplaces onboarding contractors, technicians, installers, inspectors, and repair professionals. - Insurance and risk teams reviewing contractor eligibility. - Property managers validating service vendors. - Lead-generation teams enriching contractor lists with license evidence. - Developers building repeatable contractor-license verification pipelines. ### Typical workflows 1. Search by contractor name prefix to collect possible public records. 2. Verify exact license numbers from your CRM, spreadsheet, or applicant form. 3. Export records and join them back to an internal vendor table. 4. Flag expired, inactive, missing, or mismatched records for manual review. 5. Re-run checks periodically to refresh public status and expiration signals. ### Input options The actor accepts a small set of practical inputs: - `states` — select `TX`, `CA`, or `ALL` supported states. - `contractorNames` — business, DBA, or person names to search. - `licenseNumbers` — known license numbers to verify. - `city` — optional city filter when supported by the source. - `zip` — optional ZIP filter when supported by the source. - `texasLicenseType` — TDLR license type code, with `-1` meaning all license types. - `includeDetails` — fetch detail pages for richer records when available. - `maxResults` — total number of records to save across all queries. ### Recommended input strategy For broad discovery, start with shorter name prefixes and low `maxResults` values. Texas TDLR treats name searches as prefix-oriented, so `A` or `ABC` can return many records while an exact DBA with punctuation may return fewer matches. For due diligence, prefer exact license numbers whenever your source system already has them. Exact numbers reduce ambiguity and make review queues easier to reconcile. ### Example input: Texas name search ```json { "states": ["TX"], "contractorNames": ["A"], "maxResults": 20, "includeDetails": false, "texasLicenseType": "-1" } ```` ### Example input: exact license verification ```json { "states": ["TX"], "licenseNumbers": ["18554"], "maxResults": 10, "includeDetails": true, "texasLicenseType": "-1" } ``` ### Example input: multi-state sample ```json { "states": ["ALL"], "contractorNames": ["ABC"], "maxResults": 50, "includeDetails": false, "texasLicenseType": "-1" } ``` ### Output dataset Each saved item is one public contractor license record or license-search result. Fields are normalized so you can compare results across supported state agencies. Core fields include: - `state` - `sourceAgency` - `queryType` - `query` - `licenseNumber` - `licenseType` - `businessName` - `dbaName` - `status` - `issueDate` - `expirationDate` - `classifications` - `address` - `city` - `stateCode` - `zip` - `county` - `phone` - `bondInfo` - `insuranceInfo` - `publicNotes` - `sourceUrl` - `scrapedAt` ### Example output item ```json { "state": "TX", "sourceAgency": "Texas Department of Licensing and Regulation", "queryType": "name", "query": "A", "licenseNumber": "18554", "licenseType": "Air Conditioning and Refrigeration Contractor", "businessName": "Example Mechanical Services", "dbaName": "Example Mechanical", "status": "Active", "issueDate": "2020-01-15", "expirationDate": "2026-01-15", "classifications": ["Air Conditioning"], "address": "Public address when provided", "city": "Austin", "stateCode": "TX", "zip": "78701", "county": null, "phone": null, "bondInfo": null, "insuranceInfo": null, "publicNotes": null, "sourceUrl": "https://www.tdlr.texas.gov/LicenseSearch/", "scrapedAt": "2026-06-25T04:40:00.000Z" } ``` ### Data freshness The actor reads the live public source pages during each run. The `scrapedAt` timestamp records when the lookup was performed. Government licensing databases can update independently, so treat each run as a point-in-time public-record snapshot. ### Detail pages Set `includeDetails` to `true` when you need richer status, issue date, DBA, notes, bond, insurance, or classification fields. Detail-page mode can be slower because the actor opens additional public pages for each matching record. Use `includeDetails: false` for fast discovery runs and `includeDetails: true` for smaller review queues where richer evidence matters. ### Pricing This actor uses pay-per-event pricing: - Run start: `$0.005` per run. - License record saved: tiered per item. Per-item prices by Apify user tier: | Tier | Price per license record | |---|---:| | FREE | $0.00003323 | | BRONZE | $0.000028895 | | SILVER | $0.000022538 | | GOLD | $0.000017337 | | PLATINUM | $0.000011558 | | DIAMOND | $0.00001 | You are charged for records that are successfully saved to the dataset. Keep `maxResults` low while testing a new workflow, then increase it once your inputs are returning the records you expect. ### Cost-control tips - Test with one state and a low `maxResults` value first. - Use exact license numbers when available. - Keep `includeDetails` off for broad discovery. - Use shorter name prefixes only when you intentionally want a wider candidate pool. - Export and deduplicate your own input list before large recurring checks. ### API usage Start runs with `automation-lab/contractor-license-verification-scraper` and pass the same JSON input you use in the Apify Console. ### Node.js example ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/contractor-license-verification-scraper').call({ states: ['TX'], contractorNames: ['A'], maxResults: 20, includeDetails: false, texasLicenseType: '-1' }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` ### Python example ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ['APIFY_TOKEN']) run = client.actor('automation-lab/contractor-license-verification-scraper').call(run_input={ 'states': ['TX'], 'contractorNames': ['A'], 'maxResults': 20, 'includeDetails': False, 'texasLicenseType': '-1', }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items) ``` ### cURL example ```bash curl -X POST "https://api.apify.com/v2/acts/automation-lab~contractor-license-verification-scraper/runs?token=$APIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"states":["TX"],"contractorNames":["A"],"maxResults":20,"includeDetails":false,"texasLicenseType":"-1"}' ``` ### MCP usage Use the actor through Apify MCP Server when you want Claude or another MCP client to launch contractor-license checks from a prompt. Connection URL: ```text https://mcp.apify.com/?tools=automation-lab/contractor-license-verification-scraper ``` #### Claude Code MCP setup ```bash claude mcp add apify https://mcp.apify.com/?tools=automation-lab/contractor-license-verification-scraper ``` #### MCP JSON configuration ```json { "mcpServers": { "apify": { "url": "https://mcp.apify.com/?tools=automation-lab/contractor-license-verification-scraper" } } } ``` #### MCP prompt examples Example prompts you can ask after connecting the Apify MCP server: - "Verify these Texas contractor license numbers and summarize active, expired, and missing records." - "Search the contractor license scraper for names starting with ABC in Texas and return records with expiration dates." - "Run a small due-diligence sample for this vendor list before onboarding contractors." ### Legality This actor extracts public records from government lookup pages. Use it for lawful business purposes and only process data that you are authorized to collect, store, and review. The actor does not replace legal advice, professional licensing review, or direct confirmation with a government agency. Treat results as public-record evidence that may require human review before decisions affecting vendors, applicants, or customers. ### Limitations - Coverage is limited to supported state sources. - Public websites can change field labels, search behavior, or rate limits. - Some optional fields are blank when the source does not publish them. - Name searches can return ambiguous matches. - California and Texas expose different public fields, so not every column is populated for every state. - Large detail-page runs are slower than summary searches. ### Troubleshooting no results If a search returns fewer records than expected: - Try a shorter contractor-name prefix. - Remove city or ZIP filters. - Search by exact license number. - Confirm the state source supports the license type you selected. - Increase `maxResults` only after a small run confirms the query is broad enough. ### Troubleshooting slow runs If a run is slower than expected: - Turn off `includeDetails` for initial discovery. - Lower `maxResults`. - Split very large input lists into smaller batches. - Avoid broad one-letter searches when you only need exact license checks. ### Quality notes The actor keeps one normalized dataset so downstream systems can treat Texas and California results consistently. When a state publishes richer data, fields such as `bondInfo`, `insuranceInfo`, `publicNotes`, or `classifications` are populated where available. ### Related actors These Automation Labs actors can support adjacent contractor lead-enrichment and vendor-review workflows: - Google Maps Lead Finder — discover contractor businesses and service providers. - Website Contact Finder — collect public contact pages and emails from company domains. - Business Email Finder — enrich business records with public email candidates. - Company Domain Finder — match company names to likely domains. ### FAQ: Is this an official government service? No. This is an independent Apify actor that reads public lookup pages. Always use the official source URL in the dataset when you need to review the original record. ### FAQ: Can it verify every contractor in the United States? Not yet. The current build supports selected public state databases, starting with Texas TDLR and California CSLB. More states can be added when their public lookup systems are technically reachable and commercially reliable. ### FAQ: Why are some fields empty? State agencies publish different fields. A blank optional field usually means the source page did not expose that value for the record or search mode used. ### FAQ: Should I use name search or license-number search? Use license-number search for precise verification. Use name search for discovery, lead enrichment, or when your source list does not include license numbers. ### FAQ: How should I review ambiguous matches? Export the dataset and compare `businessName`, `dbaName`, `city`, `zip`, `licenseType`, and `sourceUrl` against your internal vendor record. Ambiguous matches should be reviewed manually. ### Changelog - 0.1.0 — Initial private build with Texas TDLR and California CSLB public lookup support. # Actor input Schema ## `states` (type: `array`): State license databases to query. Texas is the most reliable high-volume source; California CSLB is attempted when selected. ## `contractorNames` (type: `array`): Business, DBA, or person names to search. TDLR treats this as a starts-with search. ## `licenseNumbers` (type: `array`): Known license numbers to verify in bulk. ## `city` (type: `string`): Optional city filter where the source supports it. ## `zip` (type: `string`): Optional ZIP filter where the source supports it. ## `texasLicenseType` (type: `string`): TDLR license type code. Use -1 for all license types, AIRREF for Air Conditioning Contractors, or another TDLR type code. ## `includeDetails` (type: `boolean`): Open each official detail page for richer status, issue date, DBA, and notes. Slower but more complete. ## `maxResults` (type: `integer`): Maximum dataset records to save across all states and queries. ## Actor input object example ```json { "states": [ "TX" ], "contractorNames": [ "A" ], "licenseNumbers": [], "texasLicenseType": "-1", "includeDetails": false, "maxResults": 20 } ``` # Actor output Schema ## `overview` (type: `string`): No description # 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 = { "states": [ "TX" ], "contractorNames": [ "A" ], "licenseNumbers": [], "city": "", "zip": "", "texasLicenseType": "-1", "includeDetails": false, "maxResults": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/contractor-license-verification-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 = { "states": ["TX"], "contractorNames": ["A"], "licenseNumbers": [], "city": "", "zip": "", "texasLicenseType": "-1", "includeDetails": False, "maxResults": 20, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/contractor-license-verification-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 '{ "states": [ "TX" ], "contractorNames": [ "A" ], "licenseNumbers": [], "city": "", "zip": "", "texasLicenseType": "-1", "includeDetails": false, "maxResults": 20 }' | apify call automation-lab/contractor-license-verification-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/contractor-license-verification-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Contractor License Verification Scraper", "description": "Verify contractor licenses from official public state lookup pages. Export status, expiration, license type, source URL, and public contact fields.", "version": "0.1", "x-build-id": "7B7T1my8HnRSQgRAj" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~contractor-license-verification-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-contractor-license-verification-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/automation-lab~contractor-license-verification-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-contractor-license-verification-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/automation-lab~contractor-license-verification-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-contractor-license-verification-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", "required": [ "states" ], "properties": { "states": { "title": "🏛️ States to search", "uniqueItems": true, "type": "array", "description": "State license databases to query. Texas is the most reliable high-volume source; California CSLB is attempted when selected.", "items": { "type": "string", "enum": [ "TX", "CA", "ALL" ], "enumTitles": [ "Texas TDLR", "California CSLB", "All supported states" ] }, "default": [ "TX" ] }, "contractorNames": { "title": "Contractor or licensee names", "type": "array", "description": "Business, DBA, or person names to search. TDLR treats this as a starts-with search.", "items": { "type": "string" } }, "licenseNumbers": { "title": "License numbers", "type": "array", "description": "Known license numbers to verify in bulk.", "items": { "type": "string" } }, "city": { "title": "City filter", "type": "string", "description": "Optional city filter where the source supports it." }, "zip": { "title": "ZIP code filter", "type": "string", "description": "Optional ZIP filter where the source supports it." }, "texasLicenseType": { "title": "Texas license type code", "type": "string", "description": "TDLR license type code. Use -1 for all license types, AIRREF for Air Conditioning Contractors, or another TDLR type code.", "default": "-1" }, "includeDetails": { "title": "Fetch detail pages", "type": "boolean", "description": "Open each official detail page for richer status, issue date, DBA, and notes. Slower but more complete.", "default": false }, "maxResults": { "title": "Maximum license records", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Maximum dataset records to save across all states and queries.", "default": 20 } } }, "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 } } } } } } } } } } ```