# Illinois PERC Card & Security Guard License Verification (`kempdata/il-security-detective-licenses`) Actor

Verify Illinois PERC cards, security guard registrations, private detective and locksmith licenses in bulk. 258,869 credentials from the official IDFPR Detective Board roster, including firearm control cards. License expiration dates and renewal windows for security hiring.

- **URL**: https://apify.com/kempdata/il-security-detective-licenses.md
- **Developed by:** [Mark Kemp](https://apify.com/kempdata) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 1,000 security 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/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

## Illinois Security Guard (PERC), Detective & Locksmith Licenses

**The entire Illinois Detective Board roster — 700,000+ records — from the official state licensing API.** That includes over 440,000 PERC (Permanent Employee Registration) cards — every registered security-guard employee in Illinois — plus firearm control cards, private detectives, security and alarm contractor agencies, locksmiths, fingerprint vendors, and canine handlers.

### Who this is for

- **Security companies** — the *new licenses* filter delivers every newly issued PERC card: people who just became employable as guards and are actively job-hunting. The freshest recruiting pipeline that exists for this workforce.
- **HR & compliance teams** — bulk-verify PERC and firearm-card status against the official state record instead of one-at-a-time lookups.
- **Insurers & underwriters** — verify contractor agency licensing and disciplinary flags for security, alarm, and locksmith businesses.
- **Suppliers** — uniforms, equipment, training courses, insurance products. New agencies and new licensees are opening wallets.
- **Background-check and investigative firms** — the licensed-PI and agency roster, filterable by city.

### What you get

One normalized record per license:

```json
{
    "record_type": "individual",
    "license_category": "PERMANENT EMPLOYEE REGISTRATION",
    "license_number": "129123456",
    "name": "JANE EXAMPLE",
    "city": "CHICAGO",
    "zip_code": "60614",
    "status": "ACTIVE",
    "issue_date": "2026-06-02",
    "expiration_date": "2029-05-31",
    "is_new_license": true,
    "ever_disciplined": false,
    "lead_reasons": ["License first issued 86 days ago"]
}
```

Export to Excel, CSV, or JSON in one click, or pull on a schedule via API.

### How to use it

1. Pick **license categories** (PERC cards, detectives, agencies, locksmiths...) or leave empty for all.
2. Pick a **record filter**: all, expiring soon, or recently issued — with the window in months.
3. Optionally narrow to one **city**, choose **individuals / agencies**, and set **maximum records** — you're only charged for what's delivered.

### One schema across every state

Every licence roster in this catalogue delivers **the same columns, in the same
order, meaning the same thing** — whichever state or profession the records came
from. Stack this dataset on top of any other KempData roster and the columns
line up.

That takes real work. Illinois writes a lapsed licensee as `NOT RENEWED` in
block capitals; Delaware writes the identical situation as `Delinquent`. Both
arrive here as `status: "lapsed"`. Names arrive SHOUTING and glued together;
they leave as `full_name`, `first_name`, `middle_name`, `last_name` in proper
case. Dates are **MM/DD/YYYY**, with an `_iso` twin for spreadsheets and imports.

**The state's own word is never thrown away.** Every translated value ships
beside a `*_raw` twin — `status_raw`, `credential_raw`, `name_raw` — holding the
source's exact string, so you can always check our work or apply your own rules.
`status_basis` tells you whether the standing is the state's published fact or
computed from the expiration date.

**`lapsed` is worth knowing about.** It is the recall pool: people who held the
licence, let it run out, and can renew. When you need experienced people in a
hurry, that is the list to call.

Full column reference: `docs/SCHEMA.md` in the source repository.

### Data source & fair use

All data comes from the Illinois IDFPR professional-licensing roster on the state's official open-data API — public records the state publishes for exactly this kind of use. No scraping, no bot games; paged requests with rate-limit handling. The Actor republishes only what the state itself makes public.

### Support

Questions and issues answered fast — usually within hours. Want another security-related license category covered? Open an issue and name it — new license products get built in the order people ask.

# Actor input Schema

## `categories` (type: `array`):

Which Detective Board license categories to include. Leave empty for all.

## `recordFilter` (type: `string`):

"Expiring soon" = licenses coming up for renewal. "New licenses" = recently issued (new guards, new agencies - fresh prospects for recruiters and suppliers).

## `expiringWithinMonths` (type: `integer`):

For the expiring-soon filter: include licenses that expire within this many months.

## `newWithinMonths` (type: `integer`):

For the new-licenses filter: include licenses first issued within this many months.

## `city` (type: `string`):

Limit to one Illinois city (e.g. CHICAGO). Leave empty for statewide.

## `includeBusinesses` (type: `boolean`):

Include agency/business records in the results.

## `includeIndividuals` (type: `boolean`):

Include individual license records in the results.

## `onlyActive` (type: `boolean`):

Skip expired, lapsed, and revoked licenses.

## `maxRecords` (type: `integer`):

Stop after this many results. You are only charged for records actually returned.

## `socrataAppToken` (type: `string`):

Optional app token for the state open-data API. Not required for normal use.

## Actor input object example

```json
{
  "categories": [],
  "recordFilter": "all",
  "expiringWithinMonths": 6,
  "newWithinMonths": 6,
  "city": "",
  "includeBusinesses": true,
  "includeIndividuals": true,
  "onlyActive": true,
  "maxRecords": 1000
}
```

# Actor output Schema

## `records` (type: `string`):

Dataset of normalized Illinois Detective Board license records with expiring-license and new-license lead flags.

# 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("kempdata/il-security-detective-licenses").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("kempdata/il-security-detective-licenses").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 kempdata/il-security-detective-licenses --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kempdata/il-security-detective-licenses"
        }
    }
}

```

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/ZvYfTdG0FFW3dd41y/builds/EmuIfXsdmAs4C7TaW/openapi.json