# Colorado and New York Business Registry Search (`automation-lab/colorado-new-york-business-registry-search`) Actor

Search Colorado and New York official business registry snapshots by legal name. Export entity IDs, types, formation dates, addresses, agents and dataset freshness for KYB research. No live certification or inactive New York entities.

- **URL**: https://apify.com/automation-lab/colorado-new-york-business-registry-search.md
- **Developed by:** [Automation Lab](https://apify.com/automation-lab) (community)
- **Categories:** Business, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.08 / 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Colorado and New York Business Registry Search

Search Colorado and New York official entity snapshots for recurring KYB research. This secretary of state business search exports normalized entity IDs, legal names, types, formation dates, published addresses, registered agents where present, and dataset freshness.

It is a snapshot research tool, not a live registry certification service. New York covers only the official **active corporations snapshot**. It cannot find inactive New York entities or retrieve filing histories.

### Who is this for?

Compliance analysts can resolve supplied legal names before reviewing official registry documents. Vendor onboarding teams can compare state-qualified IDs across recurring exports. Researchers can build reproducible entity samples without treating similarly named businesses in different states as the same legal entity.

Do not use snapshot membership alone to approve a counterparty or determine its current legal standing.

### Why use this Actor?

- One input searches two official public datasets.
- State and entity ID remain separate for safe downstream joins.
- Source type codes are preserved rather than incorrectly harmonized.
- New York DOS-process addresses are separate from principal addresses and registered agents.
- Each row includes dataset-level freshness and retrieval time.
- Overlapping name queries emit each state/entity pair once per run.

### Supported sources and scope

| State | Official source | Coverage |
|---|---|---|
| Colorado | [CDOS Business Entities](https://data.colorado.gov/d/4ykn-tg5h) | Published entity snapshot, including source-supplied statuses |
| New York | [DOS Active Corporations](https://data.ny.gov/d/n9v6-gdp6) | Active corporations as of the source snapshot period; not inactive entities |

Sources can lag official filings. `datasetUpdatedAt` comes from the portal's dataset-level `rowsUpdatedAt`, not an individual company's last-change date. A retrieval today does not mean the entity was verified today. Consult the source page for its stated period and methodology.

No login, user API key, proxy configuration, browser session or custom URL is required.

### Get started

1. Enter one or more legal-name queries in `names`.
2. Select `CO`, `NY`, or both.
3. Choose substring, starts-with, or whole-field exact matching.
4. Set the global `maxItems` limit and run.
5. Export the default dataset as JSON, CSV, Excel or another Apify-supported format.

The prefilled example searches two specific source names with whole-field exact matching:

```json
{
  "names": ["APPLEKNOCKER CLUB INC.", "ADAM'S APPLES, INC., Dissolved January 1, 1978"],
  "states": ["CO", "NY"],
  "matchMode": "exact",
  "maxItems": 10
}
```

These are example queries, not endorsements or assertions of present standing.

### Input parameters

| Parameter | Default | Meaning |
|---|---|---|
| `names` | Required | 1–50 nonempty legal-name strings, each up to 200 characters |
| `states` | `["CO","NY"]` | Nonempty subset of these two states, processed in supplied order |
| `matchMode` | `contains` | `contains`, `prefix`, or `exact` |
| `maxItems` | `100` | Global unique entity-row limit, 1–10000 |

Name matching is case-insensitive. Leading/trailing whitespace is trimmed, internal whitespace is retained. Multiple names use ANY semantics; each query is searched independently. Duplicate normalized queries and duplicate states are removed.

`contains` matches a literal substring anywhere in the legal-name field. `prefix` matches from its first character. `exact` matches the entire legal-name field, including punctuation and any published dissolution suffix. These are not fuzzy, whole-word, or linguistic searches. Apostrophes are literal; `%`, `_`, control characters and unsupported input fields are rejected, not interpreted as wildcard filters.

### Limits, ordering and deduplication

The limit is global, not per state or query. State order is outermost, name order next, and source IDs ascend within a query. A broad Colorado query can consume the limit before New York is reached. Put New York first, narrow the query, or use separate runs if you require coverage for each state.

Rows are deduplicated by `state` plus `entityId`. `matchedQuery` identifies the first matching normalized query. The same entity may appear in separate runs; downstream recurrence comparisons should use state-qualified IDs.

The Actor pages with source-ID cursors, up to 500 rows per request. A source outage, runtime limit or billing budget can stop a run before `maxItems`; the limit is not a completeness guarantee.

### Extracted data

| Field | Meaning |
|---|---|
| `state`, `entityId`, `legalName` | Source jurisdiction and entity identity |
| `entityType` | Raw type label/code, not cross-state equivalence |
| `formationDate` | CO formation date or NY initial DOS filing date, YYYY-MM-DD |
| `status` | CO published status; always null for NY because the dataset has no status column |
| `datasetScope` | Explicit source-coverage qualification |
| `formationJurisdiction` | Published formation jurisdiction |
| `principalAddress` | CO principal address or NY location address, when present |
| `serviceOfProcessName`, `serviceOfProcessAddress` | NY DOS-process addressee/address, not assumed to be an agent or principal office |
| `registeredAgent` | Name and address when actually supplied, otherwise null |
| `datasetId`, `sourceUrl` | Official dataset provenance |
| `datasetUpdatedAt`, `retrievedAt` | Dataset refresh timestamp and run retrieval timestamp |
| `matchedQuery` | First normalized name query producing this row |

Address objects use `line1`, `line2`, `city`, `state`, `postalCode`, `country`. Missing components remain null. Country is not inferred from state. A missing agent does not imply the entity has no agent.

### Example output

A source-derived New York example (timestamps will vary):

```json
{
  "state": "NY",
  "entityId": "1003146",
  "legalName": "APPLEKNOCKER CLUB INC.",
  "entityType": "DOMESTIC NOT-FOR-PROFIT CORPORATION",
  "formationDate": "1985-06-10",
  "status": null,
  "datasetScope": "New York active corporations snapshot only; not live status certification",
  "formationJurisdiction": "New York",
  "principalAddress": null,
  "serviceOfProcessName": "DIV OF MILITARY AND NAVAL",
  "serviceOfProcessAddress": {
    "line1": "AFFAIRS,LEGAL OFFICE",
    "line2": "PUBLIC SECURITY BLDG",
    "city": "STATE CAMPUS",
    "state": "NY",
    "postalCode": "12226",
    "country": null
  },
  "registeredAgent": null,
  "sourceUrl": "https://data.ny.gov/d/n9v6-gdp6",
  "datasetId": "n9v6-gdp6",
  "datasetUpdatedAt": "2026-10-17T13:41:28.000Z",
  "matchedQuery": "APPLEKNOCKER CLUB INC.",
  "retrievedAt": "2026-10-19T06:00:00.000Z"
}
```

The default dataset contains only entity rows. `SUMMARY` in the run's key-value store reports saved unique rows, scanned rows, API request count, and whether billing budget stopped collection.

### How much does it cost to search business registry snapshots?

The Actor uses pay-per-event pricing: one `start` event per valid run and one `item` event per unique emitted entity record. Empty searches have no item charge. Retries, metadata requests, duplicate matches and missing fields have no separate item events.

The start charge is $0.002 per valid run. Entity prices depend on your qualifying aggregate monthly Apify Store spend tier, not this Actor's volume alone:

| Store tier | Per entity |
|---|---:|
| FREE | $0.00207 |
| BRONZE | $0.0018 |
| SILVER | $0.001404 |
| GOLD | $0.00108 |
| PLATINUM | $0.00108 |
| DIAMOND | $0.00108 |

BRONZE examples: one entity costs $0.0038, 10 entities cost $0.020, and 100 entities cost $0.182, including one start charge. An empty valid search costs $0.002. These are Actor-event charge estimates, not guaranteed invoices; refer to the Pricing tab and platform terms for your applicable tier.

### Integrations

Use the dataset with Google Sheets for analyst review, a webhook to notify your ETL after successful completion, or an Apify integration to send rows into your own database. Keep full exports outside chat context.

For recurring research, schedule the same input, join on state/entity ID, and compare rows and source refresh timestamps in your own pipeline. This Actor does not retain a watch list, generate change alerts, certify status changes, or claim to find every new filing.

### API usage

Use an Apify token via an authorization header; never paste it into public documents.

```bash
curl -X POST \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  'https://api.apify.com/v2/acts/automation-lab~colorado-new-york-business-registry-search/runs' \
  -d '{"names":["APPLE"],"states":["NY"],"maxItems":10}'
```

JavaScript using the Apify client:

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/colorado-new-york-business-registry-search')
    .call({ names: ['APPLE'], states: ['NY'], maxItems: 10 });
if (run.status !== 'SUCCEEDED') throw new Error(`Run ${run.id}: ${run.status}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems({ limit: 10 });
console.log(items);
```

Python:

```python
import os
from apify_client import ApifyClient
client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('automation-lab/colorado-new-york-business-registry-search').call(
    run_input={'names': ['APPLE'], 'states': ['NY'], 'maxItems': 10})
if run['status'] != 'SUCCEEDED':
    raise RuntimeError(f"Run {run['id']}: {run['status']}")
print(client.dataset(run['defaultDatasetId']).list_items(limit=10).items)
```

### MCP and AI assistants

After publication, scope hosted discovery to this Actor:

```bash
claude mcp add --transport http apify \
  'https://mcp.apify.com?tools=automation-lab/colorado-new-york-business-registry-search'
```

Equivalent Claude Desktop, Cursor, and VS Code client configuration:

```json
{"mcpServers":{"apify":{"url":"https://mcp.apify.com?tools=automation-lab/colorado-new-york-business-registry-search"}}}
```

Discover actual names and argument schemas with `tools/list`. Actor selection also adds run/data helpers, not exactly one tool. Discovery is read-only, not authorization to execute.

Example prompt: “Search NY for names starting with APPLE, maximum 10 entities. Show source freshness and do not interpret snapshot membership as live certification.”

For an authorized invocation, start once and retain the run ID, status and storage IDs; these are metadata, not rows. `call-actor` waits at most 45 seconds (default 30). If nonterminal, follow the same run with `get-actor-run`, using backoff of 2, 4, 8 then at most 10 seconds and a 120-second deadline. Set client timeout above the selected server wait plus transport margin. After a timeout, recover the known run; never restart just to poll. If its ID is unknown, report uncertainty. At deadline report pending with the ID. Terminal failures may have partial rows, not successful complete output.

After success, request `get-dataset-items` with explicit dataset ID, limit, offset and needed fields. A suitable consumer budget is pages of 20 source rows, at most 100 rows or 64 KiB serialized UTF-8 admitted to model context, whichever comes first. Track source offsets, process pages host-side, and omit or summarize oversized rows with disclosure. If your client cannot intercept oversized responses, do not claim a hard byte guarantee. Report continuation offset and partial/truncated status. These consumer context limits do not reduce Actor collection limits. Discovery transport bytes and caching do not establish model token savings; no numerical savings are promised.

### FAQ and troubleshooting

**No results?** Check the selected states, spelling, punctuation and match mode. Exact matching includes the complete source name. A missing NY record may be inactive, newly filed, absent from the snapshot, or spelled differently; absence is not a legal conclusion.

**Only one state returned?** The global limit may have been consumed by the earlier state. Reverse state order or run each state separately.

**Source HTTP errors?** Network timeouts, 429 and server errors receive at most three attempts with backoff. Deterministic errors, malformed JSON or invalid source shapes fail the run. Previously saved rows are partial and must not be treated as complete.

**Address or agent is null?** The source did not supply that field. The Actor does not substitute DOS-process addresses for registered-agent addresses.

### Legality, responsible use and privacy

Use public records lawfully and independently verify material KYB decisions through official channels. Published business addresses and registered agents may identify individuals. Apply access controls, retention limits and purpose restrictions in your own systems. This Actor is not legal advice, a government service, or a certificate of good standing.

This Actor uses no AI model at runtime and sends no input or output to an AI provider. Apify run storage remains under the account's platform retention settings; delete datasets and key-value stores through Apify storage controls when no longer needed. There is no cross-run cache. For help, open an issue on the Actor's Apify page; do not post secrets or unnecessary personal data.

Failed operations send sanitized diagnostic input, exceptions and actor/build/run IDs to our private GlitchTip service for repair. Secret fields and URL queries are removed. Reports are retained for 30 days.

### Related Actors

For Colorado-only workflows needing a different field set, see [Colorado Business Entity Search Scraper](https://apify.com/automation-lab/colorado-entity-search-scraper). For another jurisdiction, see [Florida Sunbiz Business Search](https://apify.com/automation-lab/florida-sunbiz-business-search). Their supported scope and pricing are separate; this Actor does not call them.

# Changelog

This Actor's version history is a separate document: https://apify.com/automation-lab/colorado-new-york-business-registry-search/changelog.md

# Actor input Schema

## `names` (type: `array`):

1–50 legal-name queries, evaluated independently (ANY). Case-insensitive matching; leading/trailing whitespace is trimmed, internal whitespace retained. Rejects %, \_ and control characters; apostrophes are treated literally. Duplicates are removed.

## `states` (type: `array`):

Nonempty selection of CO and/or NY, in processing order. Defaults to both, CO then NY. NY covers active corporations snapshot membership only; CO includes source-supplied statuses. Later states may not be reached when the global limit is met.

## `matchMode` (type: `string`):

contains matches a literal substring anywhere in legal name, prefix matches from the first character, exact matches the entire field. All are case-insensitive; no word-boundary, fuzzy or linguistic matching. Applies identically to every state and name.

## `maxItems` (type: `integer`):

Global maximum unique state+entity-ID rows per run, not per query or state. 1–10000; zero/unlimited not supported. State order then name order determines allocation; ascending source ID within each query. Overlapping matches emit once, labeled with the first query. Billing budget/runtime/source limits can stop collection earlier.

## Actor input object example

```json
{
  "names": [
    "APPLEKNOCKER CLUB INC.",
    "ADAM'S APPLES, INC., Dissolved January 1, 1978"
  ],
  "states": [
    "CO",
    "NY"
  ],
  "matchMode": "exact",
  "maxItems": 10
}
```

# Actor output Schema

## `dataset` (type: `string`):

Unique normalized state entity records with snapshot freshness.

## `summary` (type: `string`):

Request, scanned-row and saved-entity counts; billing budget stop flag.

# 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 = {
    "names": [
        "APPLEKNOCKER CLUB INC.",
        "ADAM'S APPLES, INC., Dissolved January 1, 1978"
    ],
    "states": [
        "CO",
        "NY"
    ],
    "matchMode": "exact",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/colorado-new-york-business-registry-search").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 = {
    "names": [
        "APPLEKNOCKER CLUB INC.",
        "ADAM'S APPLES, INC., Dissolved January 1, 1978",
    ],
    "states": [
        "CO",
        "NY",
    ],
    "matchMode": "exact",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/colorado-new-york-business-registry-search").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 '{
  "names": [
    "APPLEKNOCKER CLUB INC.",
    "ADAM'\''S APPLES, INC., Dissolved January 1, 1978"
  ],
  "states": [
    "CO",
    "NY"
  ],
  "matchMode": "exact",
  "maxItems": 10
}' |
apify call automation-lab/colorado-new-york-business-registry-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/colorado-new-york-business-registry-search"
        }
    }
}
```

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/pkQLh3ksGNl7kjbkd/builds/I9URHEAibOrR3fcWA/openapi.json