# Illinois Insurance License Lookup (NPN, NAIC SBS) (`ws_tony/illinois-insurance-license`) Actor Bulk Illinois insurance producer & agency license verification via the NAIC SBS API. Paste or upload NPNs to check active status, license type, lines of authority & expiration dates — for appointment audits, E\&O reviews & license monitoring. $0.005/record. - **URL**: https://apify.com/ws\_tony/illinois-insurance-license.md - **Developed by:** [Tony](https://apify.com/ws_tony) (community) - **Categories:** Business, Lead generation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing $5.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/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 ## Illinois Insurance License Lookup API — Bulk NPN Verification (NAIC SBS) Verify Illinois insurance producer and agency license status in bulk. Paste a list of NPNs or upload a spreadsheet and this actor queries the NAIC State Based Systems API to return active status, license type, lines of authority, expiration date, and address for every producer — at $0.005 per record, no proxy required. **Who uses this?** Carrier compliance teams, MGAs, and insurance agencies who need to verify that their appointed producers and agencies hold an active Illinois insurance license. Common use cases: producer appointment audits, pre-appointment license checks, E&O compliance reviews, and ongoing license expiration monitoring. This actor automates what would otherwise be a manual lookup on the Illinois insurance department website or NAIC website. > **Part of a 24-state portfolio.** Separate actors exist for every NAIC SBS state — IL, IA, WI, NC, MO, TN, WV, CT, and more. Run each state actor independently and join results on the `npn` field to build a cross-state producer compliance report. Search the [Apify Store](https://apify.com/store) for "NAIC SBS" to find all states. --- ### ⚠️ Use NPN Lookup for Reliable License Verification — Not Name Search The NAIC SBS API returns **at most 25 results per name query** — a hard server-side cap with no pagination. Searching by last name for a common insurance agent name ("Smith", "Johnson", "Williams") will silently truncate at 25 results and you will miss producers. **The output dataset will not indicate that results were truncated** — you will simply receive the first 25 alphabetical matches with no warning. > **Truncation check:** If a name search returns exactly 25 results, assume the cap was hit and the list is incomplete. You cannot tell from the output alone whether your specific producer is in those 25. For any common name, switch to NPN lookup. **The correct workflow for bulk producer license verification:** 1. Export your appointed producer list from your AMS as a CSV or Excel file 2. Publish it to a shareable URL (Google Sheets, Dropbox, etc.) or copy the NPN column 3. Paste the URL into **NPN Spreadsheet URL** — or paste NPNs directly into **NPN List** 4. Run — you get back one record per license with no truncation risk. Most producers have one license; producers holding multiple license types (e.g., Insurance Producer and Staff Adjuster) will appear on multiple rows. > **What is an NPN?** A National Producer Number (NPN) is the unique ID assigned to every licensed insurance producer and agency by the NIPR (National Insurance Producer Registry). You can find it on a producer's license certificate, in your AMS, or by searching [nipr.com](https://nipr.com). NPNs do not change when a producer moves states or updates their name — making them the most reliable key for license verification. Name search is useful for one-off spot checks on a specific insurance agent whose name is uncommon enough to return fewer than 25 total results. For any common name or bulk verification, always use the NPN path. --- ### How to Look Up Illinois Insurance Producer Licenses #### Paste NPNs Directly (Fastest — No File Hosting Required) Open your Excel or CSV producer list, select the NPN column, and paste it straight into the **NPN List** field. That's it — the actor strips the column header and any non-numeric characters automatically, so you don't need to clean anything first. Paste one NPN per line or comma-separated — whichever is easier to copy from your spreadsheet. Results are deduplicated by license number automatically. > **Can't upload an Excel file directly?** Apify's run form doesn't support file attachments — but for most users, copying and pasting the NPN column is faster than publishing a file to a URL anyway. If you have hundreds of NPNs or run this on a schedule, the Spreadsheet URL path below avoids the copy-paste step entirely. **Run time and cost:** 100 NPNs ≈ 60 seconds, ~$0.50. 500 NPNs ≈ 5 minutes, ~$2.50. #### Link to a Spreadsheet URL (Best for Large Lists or Scheduled Runs) Paste a public download URL in the **NPN Spreadsheet URL** field and the actor downloads and parses your producer list automatically. Supported formats: `.csv`, `.xlsx`, `.xls`. The actor auto-detects any column named **NPN**, **National Producer Number**, or **Producer NPN** (case-insensitive). If no matching header is found, it assumes the first column contains NPNs. **Getting a shareable URL for your producer list:** - **Google Sheets:** File → Share → Publish to web → select *Comma-separated values (.csv)* → Publish. Copy the generated URL. - **Dropbox:** Get a share link, then change `?dl=0` to `?dl=1` at the end to force a direct download. - **Any other host:** Paste any publicly accessible direct download URL. NPNs from the file are merged with any NPNs typed in the NPN List field — duplicates are removed automatically. The actor processes all queries sequentially with a 500 ms delay between requests. Each query retries up to 3 times on transient failures — this applies to every run, not just large ones. If a query fails after all retries, a sentinel record with `"status": "QUERY FAILED"` is written to the dataset so nothing silently falls through your audit. To review failed queries, open your run in the Apify Console and click the **Log** tab — search for `[ERROR]` lines. #### One-Off Search by Name Fill in **Last Name** (and optionally **First Name**) to look up a single insurance agent or producer by name. The 25-result cap applies — for any producer whose name is common enough to appear in more than 25 records in this state, use the NPN instead. The output will not warn you if results were truncated; if the name is at all common, always verify with an NPN lookup. #### One-Off Lookup by State License Number If you have a state license number but not the NPN — common for older appointed producers whose AMS only stored the license number — fill in the **License Number** field under the One-Off Search section. The actor queries the NAIC API directly by license number and returns the matching record including the NPN, which you can then use for future bulk lookups. #### Other Run Options | Field | Default | Description | |---|---|---| | Active Licenses Only | **On** | Returns only producers with an Active license status. Excludes Expired, Inactive, Cancelled, Terminated, and Surrendered licenses. Recommended for appointment audits and compliance checks. Turn off to retrieve full license history. Note: NOT FOUND and QUERY FAILED sentinel records are always returned regardless of this setting — they are verification outcomes, not license statuses. | | Entity Type | Individual | Choose **Individual** (producers), **Business / Agency** (agency licensees), or **Both**. **Both** checks every NPN as an individual *and* as an agency in a single run — use it when your list mixes producers and agencies, or when you're unsure which an NPN is. Individuals and agencies share the same NPN, so no separate list is needed. Both makes two lookups per NPN, so it can cost up to 2× per NPN (you are only charged for records actually returned). | | State | IL | Pre-configured for Illinois. Each state in this portfolio has its own actor — find other states on the [Apify Store](https://apify.com/store). | --- ### Understanding Your Illinois License Verification Results #### NOT FOUND, NO ACTIVE LICENSE, and QUERY FAILED Records Three special sentinel records can appear in your results — understanding them is critical before wiring this actor into an appointment or compliance pipeline: - If an NPN has **no license on record** in Illinois, the actor writes `"status": "NOT FOUND"` and `"is_active": false`. The producer is not currently licensed in this state. - If an NPN exists but **all licenses are expired or terminated** (and Active Licenses Only is on), the actor writes `"status": "NO ACTIVE LICENSE"` and `"is_active": false`. - If a query **fails after 3 retries** (network error, NAIC API timeout), the actor writes `"status": "QUERY FAILED"` and `"is_active": null`. > ⚠️ **QUERY FAILED records are inconclusive — not confirmed inactive.** `is_active` is `null` on QUERY FAILED records (not `false`) to signal that the verification was not completed. Do not use a QUERY FAILED result to terminate an appointment, flag a producer as unlicensed, or make any compliance decision. Re-run or verify manually at [sbs.naic.org](https://sbs.naic.org/solar-external-lookup/). All sentinel records include every output field (nulls/empty arrays for unresolvable fields) so your spreadsheet or AMS ingestion doesn't produce column-count mismatches. Sentinel records are charged at the same rate as normal records ($0.005 each) — you are paying for the verification, not just confirmed results. A NOT FOUND result is an auditable confirmation that the producer is not licensed in Illinois. #### Unknown or New Status Values The `status` field reflects exactly what the NAIC API returns. Known values include: `Active`, `Inactive`, `Cancelled`, `Expired`, `Terminated`, `Surrendered`, `Revoked`, `Withdrawn`, `NOT FOUND`, `NO ACTIVE LICENSE`, `QUERY FAILED`. NAIC may introduce additional status strings over time. **Always use `is_active` — not `status` — for compliance filtering.** `is_active` is derived solely from the exact string `"Active"` and is reliable regardless of what status values appear. --- ### Output Data: License Status, Lines of Authority, and Producer Details Each row in the Dataset is one license record. A producer with multiple active license types (e.g., Insurance Producer and Staff Adjuster) will produce multiple rows — group by `npn` when aggregating. | Field | Example | Notes | |---|---|---| | `npn` | `"1234567"` | National Producer Number — the primary key for joining results across states. **Note:** on rare business entity records, the NAIC API returns an empty NPN; the actor outputs `null` in this case. Use `license_number` as the fallback join key for BUS records. | | `license_number` | `"79467"` | State-assigned license number. May differ from the NPN depending on the state. Always use `npn` as the join key against your AMS — never `license_number`. | | `name` | `"Mary Ann Johnson"` | Title-cased full name, First Last order for individuals; full entity name for businesses | | `first_name` | `"Mary"` | First word of given name. Always `null` for Business/Agency records. | | `middle_name` | `"Ann"` | Middle name or initial if present; `null` otherwise. Always `null` for Business/Agency records. | | `last_name` | `"Johnson"` | Surname for individual records. For Business/Agency records, contains the full entity name (same as `name`) — `first_name` will be `null`. When aggregating BUS results, use `name` rather than `last_name` to avoid confusion. | | `license_type` | `"Insurance Producer"` | License class — e.g. Insurance Producer, Adjuster, Corporation, Surplus Lines Business Entity | | `license_type_code` | `"PRO"` | Short code for license class. Known values: `PRO` (Insurance Producer), `ADJ` (Adjuster), `COR` (Corporation), `SBE` (Surplus Lines Business Entity), `PRT` (Partnership), `PAD` (Public Adjuster), `LIH` (Life and Health). Additional values may exist. | | `status` | `"Active"` | License status. Known values: `Active`, `Inactive`, `Cancelled`, `Expired`, `Terminated`, `Surrendered`, `Revoked`, `Withdrawn`, `NOT FOUND`, `NO ACTIVE LICENSE`, `QUERY FAILED`. Additional values may exist. | | `is_active` | `true` | **Use this field for compliance filtering — not `status`.** `true` only when status is exactly `"Active"`. `false` for any other confirmed status (Expired, Inactive, Cancelled, NOT FOUND, etc.). `null` for QUERY FAILED — check was inconclusive, not that the producer is inactive. | | `lines_of_authority` | `[{"loa": "Life", "effective_date": "2010-06-01"}]` | Array of LOA objects. Each has `loa` (string) and `effective_date` (ISO date or `null`). Empty array if no lines of authority are assigned. **Note for Business/Agency records:** agencies receive individual lines of authority (e.g., Casualty, Property) just like individual producers — not a generic license class label. **Note for Adjuster records:** adjuster licenses (`ADJ`, `PAD`) never carry LOA data — an empty array is correct. | | `period_start_date` | `"2026-04-01"` | Start of the **current license period** (ISO 8601) — the most recent renewal date, not the producer's original license issue date. The NAIC SBS API does not return the original issue date. Do not use this field to determine how long a producer has been licensed. | | `expiration_date` | `"2027-03-31"` | License expiration date (ISO 8601) — use this for license expiration monitoring | | `residency` | `"Resident"` | `Resident` or `Non-Resident`. Derived from the NAIC API's residency flag — if the API returns an empty or unrecognised value, this field defaults to `Non-Resident`. | | `designated_home_state` | `"Florida"` | Home state for non-resident licensees, when returned by the API. Present for some adjuster records; `null` for most producer records. | | `business_phone` | `"609-555-0100"` | Formatted as XXX-XXX-XXXX | | `address_city` | `"Charlotte"` | Title-cased city parsed from source | | `address_state` | `"TN"` | Producer's **home state**, not the search jurisdiction. Non-resident producers are licensed in this state but live elsewhere — their `address_state` will be a different state. **Do not filter by `address_state` to find all producers licensed here.** Use `is_active` and `jurisdiction` instead. | | `address_zip` | `"28262"` | 5-digit ZIP (or ZIP+4 if available); `null` if not in source data | | `address_full` | `"Charlotte, NC 28262"` | Combined city, state, ZIP — ready to paste into your AMS or CRM | | `address_raw` | `"CHARLOTTE, NC 28262"` | Trimmed source address string — fallback if parsed fields produce unexpected results | | `dba_name` | `null` | DBA name if the agency has registered one; `null` for individuals and agencies without a registered DBA | | `fein` | `null` | Federal EIN if provided by the agency; `null` for individuals and agencies that haven't supplied one. Note: many agencies on the NAIC SBS API do not provide their FEIN even when one exists. | | `source_url` | `"https://sbs.naic.org/..."` | **Direct link to this producer's record on the official NAIC SBS website.** Click to verify any record in one step — no re-searching required. Paste into your audit file or appointment letter as a citable primary-source reference. | | `scraped_at` | `"2026-05-27T12:00:00.000Z"` | ISO 8601 timestamp of when the record was fetched. Always UTC (indicated by the trailing `Z`). | > **Note:** Street address is not available from the NAIC SBS API — city, state, and ZIP are the most granular address data returned. #### Example: Individual Insurance Producer Record ```json { "npn": "2064443", "name": "Jane L Smith", "is_active": true, "status": "Active", "expiration_date": "2027-09-30", "license_type": "Insurance Producer", "license_type_code": "PRO", "lines_of_authority": [ { "loa": "Accident & Health or Sickness", "effective_date": "2000-04-10" }, { "loa": "Life", "effective_date": "2000-04-10" }, { "loa": "Variable Life and Variable Annuity", "effective_date": "2003-12-12" } ], "period_start_date": "2025-10-01", "jurisdiction": "IL", "licensee_type": "Individual", "residency": "Non-Resident", "first_name": "Jane", "middle_name": "L", "last_name": "Smith", "address_full": "Charlotte, NC 28262", "address_city": "Charlotte", "address_state": "NC", "address_zip": "28262", "address_raw": "CHARLOTTE, NC 28262", "business_phone": "717-526-7448", "license_number": "79467", "dba_name": null, "fein": null, "designated_home_state": null, "source_url": "https://sbs.naic.org/solar-external-lookup/?jurisdiction=IL&searchType=Licensee&entityType=IND&npn=2064443", "scraped_at": "2026-05-27T12:00:00.000Z" } ```` #### Example: Insurance Agency License Record ```json { "npn": "9876543", "name": "Acme Insurance Agency LLC", "is_active": true, "status": "Active", "expiration_date": "2027-05-31", "license_type": "Insurance Producer", "license_type_code": "PRO", "lines_of_authority": [ { "loa": "Casualty", "effective_date": "2015-03-01" }, { "loa": "Property", "effective_date": "2015-03-01" } ], "period_start_date": "2015-03-01", "jurisdiction": "IL", "licensee_type": "Business", "residency": "Non-Resident", "first_name": null, "middle_name": null, "last_name": "Acme Insurance Agency LLC", "address_full": "New York, NY 10001", "address_city": "New York", "address_state": "NY", "address_zip": "10001", "address_raw": "NEW YORK, NY 10001", "business_phone": "212-555-0200", "license_number": "4321098", "dba_name": null, "fein": null, "designated_home_state": null, "source_url": "https://sbs.naic.org/solar-external-lookup/?jurisdiction=IL&searchType=Licensee&entityType=BUS&npn=9876543", "scraped_at": "2026-05-27T12:00:00.000Z" } ``` #### Exporting Verification Results to Excel or CSV After a run completes, click the **Export** button in the Dataset tab to download your results. Available formats: CSV, Excel, JSON, XML, and more — no additional tools needed. *** ### Pricing: $0.005 Per License Verification **Pay-per-event** at **$0.005 per license record** returned. Sentinel records (NOT FOUND, NO ACTIVE LICENSE, QUERY FAILED) are charged at the same rate — you are paying for the verification, not just confirmed active licenses. Runs that produce zero output records are never charged. A typical bulk verification run of 100 NPNs costs $0.50. *** ### Available States: 24-State Insurance License Lookup Portfolio AL · AK · AR · CT · DC · ID · **IL** · IA · KS · MO · MT · NH · NJ · NM · NC · ND · OK · OR · RI · SD · TN · VT · WV · WI Each state has its own dedicated actor. Search the [Apify Store](https://apify.com/store) for "NAIC SBS" followed by the two-letter state code — for example, "NAIC SBS TN" for Tennessee or "NAIC SBS NC" for North Carolina. *** ### Frequently Asked Questions About Insurance License Verification **How do I check if an insurance producer is licensed in Illinois?** Paste the producer's NPN into the NPN List field and run the actor. The result will show their current license status, license type, lines of authority, and expiration date — sourced directly from the Illinois NAIC SBS database. For multiple producers, use the NPN Spreadsheet URL field to upload your full producer list. **What is an NPN and how do I find it?** An NPN (National Producer Number) is the unique identifier assigned to every licensed insurance producer and agency by the NIPR (National Insurance Producer Registry). Find it on a producer's license certificate, in your agency management system (AMS), or by searching [nipr.com](https://nipr.com). NPNs do not change when a producer moves states or updates their name. **How do I verify insurance agency licenses in Illinois?** Switch the Entity Type field to "Business / Agency" and paste the agency's NPN. The actor returns the agency's license type, DBA name, and FEIN (when provided). If your list mixes individual producers and agencies — or you're not sure which an NPN is — set Entity Type to **Both** and the actor checks each NPN as an individual *and* as an agency in a single run, so you no longer need to run it twice. Note: the NAIC SBS API returns the agency's license class as its line of authority rather than individual lines (Life, Property, Casualty). To verify specific line authority, look up the individual producers appointed under that agency. **Can I verify producers licensed in multiple states at once?** Each state in this portfolio has its own dedicated actor. Run them independently — you can start multiple runs simultaneously from the Apify Console — then join the results on the `npn` field. For example: download results from the IL and IL actors as two CSV files. In Excel, use `=VLOOKUP(A2,IL_results!$A:$Z,MATCH("is_active",IL_results!$1:$1,0),FALSE)` where column A contains the NPN column. Any producer with `is_active=TRUE` in both files is licensed in both states. Search the Apify Store for "NAIC SBS" to find actors for all 24 supported states. **What does "NOT FOUND" mean in my results?** The NPN has no license record in Illinois — the producer is not currently licensed in this state. This is a confirmed compliance check result, not an error. NOT FOUND still counts toward billing at $0.005 because the verification was completed. **What does "QUERY FAILED" mean and what should I do?** The actor could not reach the NAIC API for that NPN after 3 retries — usually a temporary network issue, not a problem with the producer's license. Re-run the actor with just the failed NPNs, or verify them manually at [sbs.naic.org](https://sbs.naic.org/solar-external-lookup/). Do not use a QUERY FAILED result to make compliance or appointment decisions. **What does "Cancelled" status mean?** Cancelled is a license status returned directly by the NAIC SBS API. Like Inactive, Terminated, and Expired, it indicates the producer no longer holds an active license in this state — `is_active` will be `false`. The distinction between Cancelled, Terminated, and Surrendered is made by the state insurance department and reflected as-is from the official NAIC data. **Why does a producer appear on more than one row?** A producer can hold more than one license type simultaneously — for example, both an Insurance Producer license and an Adjuster license. The actor returns one row per license (deduplicated by license number). When aggregating results, group by `npn` rather than counting rows. **Why does my name search return results that don't match what I searched for?** The NAIC API performs a prefix match on last name and returns results in alphabetical order, capped at 25. Searching for a business name like "Allstate" returns the first 25 business names that start with that prefix — not just exact matches. For reliable lookups of a specific entity, use the NPN field. **Is this data official and legally defensible?** Yes. The data comes directly from the NAIC State Based Systems public lookup — the same database used by state insurance regulators. Each record includes a `source_url` linking directly to the producer's page on the official NAIC SBS site — click it to verify any record in one step and cite the URL in audits, appointment files, or E\&O documentation. **Is there a free alternative?** The NAIC SBS website ([sbs.naic.org](https://sbs.naic.org/solar-external-lookup/)) offers free individual lookups. This actor is for teams that need to verify dozens, hundreds, or thousands of producers in a repeatable, auditable, automated way — the manual website does not support bulk lookup or CSV export. *** ### Data Source: NAIC State Based Systems (Official Government Data) [NAIC State Based Systems External Lookup](https://sbs.naic.org/solar-external-lookup/) — the official state insurance regulator database, maintained by the National Association of Insurance Commissioners. Public data, no authentication required. # Actor input Schema ## `npnList` (type: `string`): Paste your NPN column straight from Excel or CSV — the header row and any non-numeric characters are stripped automatically, so no cleanup is needed. One NPN per line or comma-separated. NPNs are up to 10-digit numbers found on a producer's license certificate, on NIPR.com, or in your AMS. (Pre-filled with a sample Illinois NPN so you can run it right away — replace it with your own list.) 100 NPNs ≈ 60 seconds and ~$0.50. For very large or scheduled lists, use the Spreadsheet URL field below instead. ## `npnFileUrl` (type: `string`): Direct download URL to a CSV or Excel file (.csv, .xlsx, .xls) containing your producer NPNs. The actor auto-detects any column named NPN, National Producer Number, or Producer NPN (case-insensitive). Works with Google Sheets (File → Share → Publish to web → CSV), Dropbox (change ?dl=0 to ?dl=1 in your share link), or any publicly accessible file URL. NPNs from the file are combined with any NPNs typed in the NPN List field above. ## `entityType` (type: `string`): Whose licenses to look up. Individual = producers. Business / Agency = agency licensees. Both = checks every NPN as an individual AND as an agency in a single run — use this if your list mixes producers and agencies, or if you're not sure which an NPN is. Individuals and agencies share the same NPN, so no separate list is needed. Note: Both makes two lookups per NPN, so it can cost up to 2× per NPN (you are only charged for records actually returned). ## `activeOnly` (type: `boolean`): When checked, only records with an Active license status are returned. Expired, Inactive, Terminated, Cancelled, and Surrendered licenses are excluded. Recommended for most compliance workflows. Turn off only if you need a full license history. Note: NOT FOUND and QUERY FAILED sentinel records are always included regardless of this setting — they represent verification outcomes, not license statuses. ## `lastName` (type: `string`): Search by last name instead of NPN. The API returns at most 25 results per name search — use NPN List above for bulk verification. ## `firstName` (type: `string`): Optional. Narrows a last-name search. ## `licenseNumber` (type: `string`): Optional. Direct lookup by state license number. ## `jurisdiction` (type: `string`): Two-letter state code. Pre-filled for this actor's state. Each state in this portfolio has its own dedicated actor — if you need a different state, find that state's actor on the Apify Store instead of changing this field. ## Actor input object example ```json { "npnList": "21693299", "entityType": "IND", "activeOnly": true, "jurisdiction": "IL" } ``` # 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 = { "npnList": "21693299" }; // Run the Actor and wait for it to finish const run = await client.actor("ws_tony/illinois-insurance-license").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 = { "npnList": "21693299" } # Run the Actor and wait for it to finish run = client.actor("ws_tony/illinois-insurance-license").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 '{ "npnList": "21693299" }' | apify call ws_tony/illinois-insurance-license --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=ws_tony/illinois-insurance-license", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Illinois Insurance License Lookup (NPN, NAIC SBS)", "description": "Bulk Illinois insurance producer & agency license verification via the NAIC SBS API. Paste or upload NPNs to check active status, license type, lines of authority & expiration dates — for appointment audits, E&O reviews & license monitoring. $0.005/record.", "version": "0.1", "x-build-id": "af8FJ1pYYCnTZFS1p" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ws_tony~illinois-insurance-license/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ws_tony-illinois-insurance-license", "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/ws_tony~illinois-insurance-license/runs": { "post": { "operationId": "runs-sync-ws_tony-illinois-insurance-license", "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/ws_tony~illinois-insurance-license/run-sync": { "post": { "operationId": "run-sync-ws_tony-illinois-insurance-license", "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": [ "jurisdiction" ], "properties": { "npnList": { "title": "NPN List (paste here — easiest)", "type": "string", "description": "Paste your NPN column straight from Excel or CSV — the header row and any non-numeric characters are stripped automatically, so no cleanup is needed. One NPN per line or comma-separated. NPNs are up to 10-digit numbers found on a producer's license certificate, on NIPR.com, or in your AMS. (Pre-filled with a sample Illinois NPN so you can run it right away — replace it with your own list.) 100 NPNs ≈ 60 seconds and ~$0.50. For very large or scheduled lists, use the Spreadsheet URL field below instead." }, "npnFileUrl": { "title": "NPN Spreadsheet URL (optional — for large/scheduled lists)", "type": "string", "description": "Direct download URL to a CSV or Excel file (.csv, .xlsx, .xls) containing your producer NPNs. The actor auto-detects any column named NPN, National Producer Number, or Producer NPN (case-insensitive). Works with Google Sheets (File → Share → Publish to web → CSV), Dropbox (change ?dl=0 to ?dl=1 in your share link), or any publicly accessible file URL. NPNs from the file are combined with any NPNs typed in the NPN List field above." }, "entityType": { "title": "Entity Type", "enum": [ "IND", "BUS", "BOTH" ], "type": "string", "description": "Whose licenses to look up. Individual = producers. Business / Agency = agency licensees. Both = checks every NPN as an individual AND as an agency in a single run — use this if your list mixes producers and agencies, or if you're not sure which an NPN is. Individuals and agencies share the same NPN, so no separate list is needed. Note: Both makes two lookups per NPN, so it can cost up to 2× per NPN (you are only charged for records actually returned).", "default": "IND" }, "activeOnly": { "title": "Active licenses only", "type": "boolean", "description": "When checked, only records with an Active license status are returned. Expired, Inactive, Terminated, Cancelled, and Surrendered licenses are excluded. Recommended for most compliance workflows. Turn off only if you need a full license history. Note: NOT FOUND and QUERY FAILED sentinel records are always included regardless of this setting — they represent verification outcomes, not license statuses.", "default": true }, "lastName": { "title": "Last Name (single lookup)", "type": "string", "description": "Search by last name instead of NPN. The API returns at most 25 results per name search — use NPN List above for bulk verification." }, "firstName": { "title": "First Name", "type": "string", "description": "Optional. Narrows a last-name search." }, "licenseNumber": { "title": "License Number", "type": "string", "description": "Optional. Direct lookup by state license number." }, "jurisdiction": { "title": "State (Jurisdiction)", "enum": [ "AL", "AK", "AR", "CT", "DC", "ID", "IL", "IA", "KS", "MO", "MT", "NH", "NJ", "NM", "NC", "ND", "OK", "OR", "RI", "SD", "TN", "VT", "WV", "WI" ], "type": "string", "description": "Two-letter state code. Pre-filled for this actor's state. Each state in this portfolio has its own dedicated actor — if you need a different state, find that state's actor on the Apify Store instead of changing this field.", "default": "IL" } } }, "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 } } } } } } } } } } ```