# Business License Verification and Lead Finder (`lavender_whistle/business-licenses-monitor`) Actor

Verify business licenses and find new licensees as B2B leads from public city Socrata data. Clean rows: legal and DBA name, license type, status, address, ward, issue and expiry dates, activity, and a deep link. Zero-config default returns the newest active licenses. Points at any Socrata portal.

- **URL**: https://apify.com/lavender\_whistle/business-licenses-monitor.md
- **Developed by:** [Cathal Judge](https://apify.com/lavender_whistle) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$4.00 / 1,000 result rows

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 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

## Business License Verification and Lead Finder

**Apify Store title:** `Business License Verification and Lead Finder`

**Apify Store description:**

> Verify any business license and find brand-new licensees as B2B leads, straight from public city Socrata data (default: City of Chicago). Get clean rows: legal and DBA name, license type, status, full address, ward and precinct, issue and expiry date, business activity, and a deep verification link. Ideal for compliance and vendor-verification teams, B2B sales prospecting new businesses, and franchise scouts. Zero-config default run returns the newest active licenses immediately. Points at any Socrata licensing portal. 100% public data: no login, no PII.

### Source + legality

`GET https://data.cityofchicago.org/resource/r5kz-chrr.json?$where=...&$order=...&$limit=...` - the City of Chicago Business Licenses dataset on the public Socrata SODA API. Statutorily public municipal data. No authentication is required for modest use; an optional Socrata app token raises rate limits. No consumer PII. Set `datasetUrl` to any other Socrata licensing dataset to run it against a different city or portal.

### Zero-config default run

Empty input returns the most-recent ACTIVE Chicago business licenses (`license_status = AAI`, sorted by `date_issued` newest-first) so the Store "try it" button works on first click.

### Inputs

`datasetUrl, searchTerm, statusField, activeStatus, orderField, maxResults, appToken` - all optional. Use `searchTerm` to verify a named business (free-text search across the record) or to find leads by keyword.

### Output fields

`legalName, doingBusinessAs, licenseType, licenseCode, status, statusLabel, businessActivity, address, city, state, zip, ward, precinct, wardPrecinct, neighborhood, dateIssued, expirationDate, licenseNumber, latitude, longitude, source`

The `source` field is a stable per-row deep link built on Socrata's universal `:id`, so it works on whatever portal the actor is pointed at.

### Run locally (no Apify account)

```bash
npm install
npm test --workspace actors/business-licenses-monitor
## or run the actor directly:
node actors/business-licenses-monitor/src/main.js
```

### Proposed pricing (set in Apify at publish - CJ-gated)

Pay-Per-Event in the documented winning band:

- **~$0.004 per license row returned**

Pricing is NOT set here; it is configured on the Apify Store at publish, CJ-gated. No account, no publish, no spend happens in this repo.

# Actor input Schema

## `datasetUrl` (type: `string`):

Socrata SODA resource endpoint (must end in .json). Default is City of Chicago Business Licenses. Point it at any Socrata licensing portal, e.g. another city's dataset.

## `searchTerm` (type: `string`):

Free-text filter across the whole record. Use a business name to verify a specific licensee, or a keyword to find leads. Leave blank to list the newest licenses.

## `statusField` (type: `string`):

Dataset column used to filter to active licenses. Default is Chicago's license\_status. Change it only if a different portal names the column differently.

## `activeStatus` (type: `string`):

Status value that means active/issued. Default AAI is Chicago's active code. Leave blank to return licenses of every status.

## `orderField` (type: `string`):

Date column to sort by, newest first, so the freshest licenses come first. Default is Chicago's date\_issued.

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

Maximum number of license rows to return per run.

## `appToken` (type: `string`):

Optional Socrata application token for higher rate limits. Not required for modest use; leave blank to run unauthenticated.

## Actor input object example

```json
{
  "datasetUrl": "https://data.cityofchicago.org/resource/r5kz-chrr.json",
  "searchTerm": "",
  "statusField": "license_status",
  "activeStatus": "AAI",
  "orderField": "date_issued",
  "maxResults": 25,
  "appToken": ""
}
```

# 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 = {
    "datasetUrl": "https://data.cityofchicago.org/resource/r5kz-chrr.json",
    "searchTerm": "",
    "statusField": "license_status",
    "activeStatus": "AAI",
    "orderField": "date_issued",
    "maxResults": 25,
    "appToken": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("lavender_whistle/business-licenses-monitor").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 = {
    "datasetUrl": "https://data.cityofchicago.org/resource/r5kz-chrr.json",
    "searchTerm": "",
    "statusField": "license_status",
    "activeStatus": "AAI",
    "orderField": "date_issued",
    "maxResults": 25,
    "appToken": "",
}

# Run the Actor and wait for it to finish
run = client.actor("lavender_whistle/business-licenses-monitor").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 '{
  "datasetUrl": "https://data.cityofchicago.org/resource/r5kz-chrr.json",
  "searchTerm": "",
  "statusField": "license_status",
  "activeStatus": "AAI",
  "orderField": "date_issued",
  "maxResults": 25,
  "appToken": ""
}' |
apify call lavender_whistle/business-licenses-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=lavender_whistle/business-licenses-monitor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/jNS9kcxbDtb69ZBnE/builds/kwJCkCgAOAarePsvS/openapi.json