# US Secretary of State Business Search (NY, CO, OR, CT) (`groundtruth/us-state-business-search`) Actor

Search official US state business registers for KYB checks and new LLC lists: New York, Colorado, Oregon and Connecticut. Official open data, one consistent schema, every record links to the state source.

- **URL**: https://apify.com/groundtruth/us-state-business-search.md
- **Developed by:** [Ground Truth](https://apify.com/groundtruth) (community)
- **Categories:** Business, AI, Lead generation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 business entity 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?

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

## US Secretary of State Business Search (NY, CO, OR, CT)

Search official US state business registers for **KYB (know your business) checks** and **new LLC lists**, in one consistent format. It covers New York, Colorado, Oregon and Connecticut, using the open data each state publishes for public reuse. **Every record links to the state data row it came from**, so any value can be checked at the source in one click.

Use it when you need to:

- Check that a supplier, customer or counterparty is a real registered entity, and whether it is active, delinquent or dissolved
- Build a list of newly formed LLCs and corporations in a date window, newest first
- Look up entities by the state's own entity number
- Enrich a company list with entity type, formation date, state of formation and business city

For AI agents: call it to confirm that a named company exists in a state register and to get its status, type and formation date with a link that proves it.

### What it does not do

- It covers four states, not all fifty. Other states do not publish a register as open data without a signup, so they are not included.
- It does not return officers, directors, owners or individual registered agents. A registered agent appears only when it is a company, such as a commercial agent service.
- It does not return street addresses, emails or phone numbers. Business location is city, state and ZIP.
- New York and Oregon publish active entities only. An entity missing from their results is either inactive or not registered there; this tool cannot tell which. Colorado and Connecticut publish every status.
- Data is as fresh as each state's own publishing schedule. When tested on 2026-10-18, New York, Colorado and Connecticut already held entities formed on 2026-10-16, and Oregon held entities formed up to 2026-10-13. The `retrieved_at` field says when the Actor read the data, not when the state last updated it.
- It is not legal, tax or compliance advice, and a state register entry is not proof of what a business does.

### Sample output

Input:

```json
{ "entity_numbers": ["19971030166"], "states": ["CO"] }
```

Output:

```json
{
  "legal_name": "PETSMART CHARITIES, INC.",
  "entity_number": "19971030166",
  "state": "CO",
  "entity_type": "Foreign Nonprofit Corporation",
  "entity_type_code": "FNC",
  "status": "Good Standing",
  "status_detail": null,
  "status_group": "active",
  "formation_date": "1997-02-27",
  "jurisdiction_of_formation": "AZ",
  "principal_city": "Phoenix",
  "principal_state": "AZ",
  "principal_zip": "85027",
  "address_type": "principal_office",
  "registered_agent_company": "CORPORATE CREATIONS NETWORK INC.",
  "verify_url": "https://data.colorado.gov/resource/4ykn-tg5h.json?entityid=19971030166",
  "state_record_url": "https://www.sos.state.co.us/biz/BusinessEntityDetail.do?quitButtonDestination=BusinessEntityResults&fileId=19971030166",
  "state_search_url": "https://www.sos.state.co.us/biz/BusinessEntityCriteria.do",
  "source_dataset": "data.colorado.gov 4ykn-tg5h (Business Entities in Colorado)",
  "source_license": "Public Domain (declared on the dataset by the publisher, Colorado Department of State)",
  "retrieved_at": "2026-10-18T12:00:00Z"
}
```

**Check it yourself:** open `state_record_url` and compare the name, form, status, formation date and principal office with the record above. The `verify_url` shows the raw state data row in your browser.

A handled error, for an input with nothing to search for (`{}`): the run stops with the message "Give at least one of: query (a company name), entity_numbers, or formed_after (a date, for a list of newly formed businesses)." Nothing is charged.

### Configuration

| Input | Type | Default | Meaning |
|---|---|---|---|
| `query` | text | `bakery` | Part of a legal business name. Not case sensitive. |
| `entity_numbers` | list | none | State entity numbers, digits only, up to 200. Numbers are not unique across states, so pick the state too. |
| `states` | list | all four | Any of NY, CO, OR, CT. Results are shared across the states chosen. |
| `formed_after` | date | none | `YYYY-MM-DD`. Use it for new business lists. Results are newest first. |
| `formed_before` | date | none | `YYYY-MM-DD`. Combine with `formed_after` for a window. |
| `entity_kind` | choice | `any` | `llc`, `corporation` (for profit), `nonprofit`, `partnership`. |
| `status` | choice | `any` | `active`, `active_or_delinquent`, `inactive`. New York and Oregon are skipped for `inactive`. |
| `max_results` | number | 25 | 1 to 5000, shared across states. You pay per entity returned. |

You must give at least one of `query`, `entity_numbers`, `formed_after` or `formed_before`.

#### Output fields

| Field | Meaning |
|---|---|
| `legal_name` | Name as the state publishes it. Colorado appends notes such as ", Dissolved July 20, 2026" to some names; they are kept as published. |
| `entity_number` | The state's entity number, as text. |
| `state` | NY, CO, OR or CT. |
| `entity_type` | The state's own type. Colorado codes are expanded to the wording the state shows; the raw code is in `entity_type_code`. |
| `status`, `status_detail` | The state's status text. Connecticut adds a sub-status such as "Annual report past due". |
| `status_group` | `active`, `delinquent` (still registered but behind on filings or already warned), `inactive` (dissolved, withdrawn, revoked, merged) or `other`. |
| `formation_date` | The date of the state's first filing for the entity. For an out-of-state entity registered in this state, that is its registration date here. Null when the state has no usable date. |
| `jurisdiction_of_formation` | Where the entity was formed, as the state records it. |
| `principal_city`, `principal_state`, `principal_zip` | Business location. |
| `address_type` | `principal_office`, `business_address`, `mailing`, or `service_of_process`. New York publishes a location address for only about one entity in twelve, so for the rest the address the state forwards legal papers to is used and labelled. |
| `registered_agent_company` | The registered agent, only when it is a company. Null when the agent is a person, missing, or not clearly a company. |
| `verify_url` | The state data row for this entity, as raw JSON, checkable in any browser. |
| `state_record_url` | The state's own web page for the entity (Colorado and Oregon). |
| `source_dataset`, `source_license`, `retrieved_at` | Where the row came from, its licence, and when it was read. |

#### Errors

Every error is a plain sentence and nothing is charged. Bad input names the field and how to fix it. If one state does not answer, the other states still return results and the run log says which state is missing. If every state fails, the run fails with the reason. A state that is rate limiting is retried twice and then given up on.

### Pricing

Pay per event: **$0.002 per entity returned**, which is $2 per 1,000 entities, plus Apify's standard small start fee. Searches that match nothing, invalid input and failed states are not charged.

### Sources and licences

Open data from the state portals: New York Department of State (OPEN-NY terms of use, free reuse), Colorado Department of State (Public Domain), Oregon Secretary of State (public domain by statute ORS 276A.368) and Connecticut Secretary of the State (Public Domain). The run log carries the attribution for each state that returned data.

# Actor input Schema

## `query` (type: `string`):

Part of a legal business name, for example 'acme' or 'blue ridge bakery'. Matching ignores upper and lower case. Leave empty if you search by entity number or only want newly formed businesses. Defaults to 'bakery' so the Actor has a working example run.

## `entity_numbers` (type: `array`):

Look up specific entities by the state's own entity number, digits only. Numbers are not unique across states (New York and Connecticut both issue seven-digit numbers), so pick the state too.

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

Leave empty to search all four. Results are shared across the states you pick.

## `formed_after` (type: `string`):

Date as YYYY-MM-DD. Use it for a list of newly formed businesses, for example 2026-10-01. Results are sorted newest first.

## `formed_before` (type: `string`):

Date as YYYY-MM-DD. Combine with 'Formed on or after' for a date window.

## `entity_kind` (type: `string`):

Limit results to one kind of business. 'Any' returns every kind the register holds.

## `status` (type: `string`):

'Any' returns every status the state publishes. New York and Oregon publish active entities only, so a search for inactive ones skips them. 'Delinquent' means still registered but behind on filings, or already warned by the state.

## `max_results` (type: `integer`):

Total entities to return, shared across the selected states. You are charged per entity returned.

## Actor input object example

```json
{
  "query": "bakery",
  "entity_numbers": [
    "20268272035"
  ],
  "states": [
    "NY",
    "CO",
    "OR",
    "CT"
  ],
  "formed_after": "2026-10-01",
  "formed_before": "2026-10-31",
  "entity_kind": "any",
  "status": "any",
  "max_results": 25
}
```

# Actor output Schema

## `entities` (type: `string`):

No description

## `entitiesCsv` (type: `string`):

No description

## `runDetails` (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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "query": "bakery",
    "states": [
        "NY",
        "CO",
        "OR",
        "CT"
    ],
    "max_results": 25
};

// Run the Actor and wait for it to finish
const run = await client.actor("groundtruth/us-state-business-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 = {
    "query": "bakery",
    "states": [
        "NY",
        "CO",
        "OR",
        "CT",
    ],
    "max_results": 25,
}

# Run the Actor and wait for it to finish
run = client.actor("groundtruth/us-state-business-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 '{
  "query": "bakery",
  "states": [
    "NY",
    "CO",
    "OR",
    "CT"
  ],
  "max_results": 25
}' |
apify call groundtruth/us-state-business-search --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,groundtruth/us-state-business-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/QEtHwNax2E5j5YY6A/builds/chQfBrbYTEYs4cKay/openapi.json