# Colorado Business Entities Scraper (`automation-lab/colorado-entity-search-scraper`) Actor

Search and export official Colorado business entity records for verification and recurring registry checks.

- **URL**: https://apify.com/automation-lab/colorado-entity-search-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

## Colorado Business Entities Scraper

Search and export **Colorado business entities** from the official Colorado Open Data registry.

Use company names, entity IDs, status, type, principal city, registered-agent name, or formation dates to retrieve structured records for verification and recurring registry checks.

The Actor returns entity identifiers, status, formation details, addresses, registered agents, official source-record URLs, and filing-history API links.

### What does Colorado Business Entities Scraper do?

Colorado Business Entities Scraper turns the Colorado Department of State's public business-entity dataset into a configurable Apify workflow.

It can:

- search registered entity names with case-insensitive terms;
- look up exact Colorado entity IDs;
- filter by entity status and entity type code;
- filter by principal city;
- search registered-agent person or organization names;
- select entities by formation-date range;
- sort results by name or formation date;
- export up to 10,000 matching records per run;
- link every result to official record and filing-history data.

Results are saved in the default Apify dataset for JSON, CSV, Excel, XML, RSS, and integration-friendly export.

### Who is this Colorado registry scraper for?

**Compliance and KYB teams** can refresh public registration facts before a review.

**Sales operations teams** can build bounded lists by city, formation date, or current status.

**Researchers and analysts** can export a reproducible slice of Colorado SOS data without writing SoQL queries.

**Developers and data engineers** can call the Actor through the Apify API, schedules, webhooks, Make, Zapier, or MCP.

**Operations teams** can schedule the same filters and compare datasets between runs in their own pipeline.

This Actor does not decide whether a business is trustworthy, licensed, or suitable for a transaction.

### Why use this Actor?

- **Official source:** records come from Colorado Open Data dataset `4ykn-tg5h`.
- **No login:** the selected source is a public, keyless JSON API.
- **Useful filters:** users do not need to learn Socrata query syntax.
- **Structured output:** addresses and registered-agent details are normalized into objects.
- **Stable pagination:** results use deterministic ordering and entity-ID deduplication.
- **Source traceability:** every row includes record, filing-history, dataset, and official-search links.
- **Cost-efficient route:** direct API requests avoid browser and proxy overhead.
- **Fail-closed validation:** malformed IDs, dates, filters, and limits stop with a clear error.

### What Colorado business entity data is extracted?

| Field | Meaning |
| --- | --- |
| `entityId` | Colorado Secretary of State entity identifier |
| `entityName` | Registered entity name |
| `status` | Current status published in the open dataset |
| `entityType` | Colorado entity type code, such as `DLLC` |
| `jurisdictionOfFormation` | Formation jurisdiction reported by the source |
| `formationDate` | Entity formation date |
| `principalAddress` | Published principal address |
| `mailingAddress` | Published mailing address |
| `registeredAgent` | Person or organization name and published addresses |
| `sourceDatasetUrl` | Official dataset page |
| `sourceRecordApiUrl` | Official API query for this entity |
| `filingHistoryApiUrl` | Official transaction-history API query for this entity |
| `officialBusinessSearchUrl` | Colorado SOS business-search page |
| `retrievedAt` | UTC retrieval time |

Some fields are absent when the source does not publish a value.

### Getting started

1. Open the Actor in Apify Console.
2. Enter at least one search filter.
3. Keep `maxItems` small for the first run.
4. Click **Start**.
5. Open the **Dataset** tab when the run succeeds.
6. Export the rows or connect them to your workflow.

A simple name search:

```json
{
  "searchTerms": ["APIFY"],
  "maxItems": 10
}
```

### Input parameters

| Input | Type | Description |
| --- | --- | --- |
| `searchTerms` | `string[]` | Entity-name substrings; any term may match |
| `entityIds` | `string[]` | Exact numeric Colorado entity IDs |
| `statuses` | `string[]` | Exact statuses, case-insensitive |
| `entityTypes` | `string[]` | Exact Colorado entity type codes |
| `principalCities` | `string[]` | Exact principal cities, case-insensitive |
| `agentName` | `string` | Substring matched against agent person or organization fields |
| `formedFrom` | `YYYY-MM-DD` | Inclusive earliest formation date |
| `formedTo` | `YYYY-MM-DD` | Inclusive latest formation date |
| `sortBy` | `string` | `entityNameAsc`, `formationDateAsc`, or `formationDateDesc` |
| `maxItems` | `integer` | Maximum unique entities, from 1 to 10,000 |

All supplied filters from different fields are combined with **AND**.

Multiple values inside name, ID, status, type, or city fields are combined as alternatives.

### Search examples

Find entities containing a company-name term:

```json
{
  "searchTerms": ["APIFY"],
  "maxItems": 10
}
```

Look up one exact entity:

```json
{
  "entityIds": ["20241583107"],
  "maxItems": 1
}
```

Find recently formed, good-standing Colorado Springs entities:

```json
{
  "principalCities": ["Colorado Springs"],
  "statuses": ["Good Standing"],
  "formedFrom": "2026-07-01",
  "sortBy": "formationDateDesc",
  "maxItems": 25
}
```

Search by registered-agent organization or person name:

```json
{
  "agentName": "Registered Agent",
  "statuses": ["Good Standing"],
  "maxItems": 100
}
```

### Output example

A representative dataset item has this shape:

```json
{
  "entityId": "20250001234",
  "entityName": "Sample Mountain Services LLC",
  "status": "Good Standing",
  "entityType": "DLLC",
  "jurisdictionOfFormation": "CO",
  "formationDate": "2025-01-15T00:00:00.000",
  "principalAddress": {
    "address1": "100 Sample Street",
    "city": "Denver",
    "state": "CO",
    "postalCode": "80202",
    "country": "US"
  },
  "registeredAgent": {
    "fullName": "Sample Registered Agent",
    "organizationName": "Sample Agent Services Inc."
  },
  "sourceDatasetUrl": "https://data.colorado.gov/d/4ykn-tg5h",
  "sourceRecordApiUrl": "https://data.colorado.gov/resource/4ykn-tg5h.json?entityid=20250001234",
  "filingHistoryApiUrl": "https://data.colorado.gov/resource/casm-dbbj.json?entityid=20250001234",
  "officialBusinessSearchUrl": "https://www.sos.state.co.us/biz/BusinessEntityCriteriaExt.do",
  "retrievedAt": "2025-01-15T12:00:00.000Z"
}
```

The example values are anonymized; live rows preserve the public source values.

### How much does it cost to search Colorado business entities?

The Actor uses pay-per-event pricing:

- a one-time **Start** charge for each run;
- an **Item processed** charge for each entity saved to the dataset;
- no separate charge for addresses, agent details, or source links included in that item.

Pricing starts at **$0.005 per run** and the BRONZE tier is **$0.003464 per saved entity**.

The per-item rate decreases across Apify usage tiers.

At BRONZE rates:

| Saved entities | BRONZE calculation |
| ---: | --- |
| 1 | start fee + 1 × item rate |
| 25 | start fee + 25 × item rate |
| 100 | start fee + 100 × item rate |
| 1,000 | start fee + 1,000 × item rate |

Multiply the live per-item tier rate by the number of saved entities and add the one-time run fee. Apify rounds billing according to platform rules. Check the live pricing panel before a production run.

### Recurring verification workflow

Use a stable filter and Apify schedule to refresh the same registry segment.

A typical flow is:

1. run daily or weekly with the required city, status, or agent filters;
2. export the dataset through an integration or webhook;
3. key records by `entityId` in your database;
4. compare status, address, agent, and formation fields with the previous snapshot;
5. route meaningful differences for review;
6. verify consequential decisions against the live official record.

The Actor returns current source records. It does not itself calculate changes or retain a historical snapshot.

### Export and integration patterns

**Spreadsheet refresh:** export the default dataset as CSV or Excel.

**Database upsert:** use `entityId` as the stable source key and `retrievedAt` as collection metadata.

**KYB intake:** look up a supplied entity ID, then send the typed row to a review queue.

**New-registration feed:** use `formedFrom`, `formedTo`, and `formationDateDesc` on a schedule.

**Agent research:** combine `agentName` with status, city, or date filters.

**Filing enrichment:** follow `filingHistoryApiUrl` only when your downstream workflow needs transaction rows.

### Run with the Apify API using cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~colorado-entity-search-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchTerms":["APIFY"],"maxItems":10}'
```

To wait for completion and obtain dataset items in one request, use the Apify synchronous dataset endpoint when the expected run fits its timeout.

### Run with JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/colorado-entity-search-scraper').call({
  principalCities: ['Colorado Springs'],
  statuses: ['Good Standing'],
  formedFrom: '2026-07-01',
  sortBy: 'formationDateDesc',
  maxItems: 25,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Run with Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("automation-lab/colorado-entity-search-scraper").call(run_input={
    "entityIds": ["20241583107"],
    "maxItems": 1,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use with MCP and AI agents

**Claude Code setup**

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/colorado-entity-search-scraper"
```

**Claude Desktop setup**

Add this server to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/colorado-entity-search-scraper"
    }
  }
}
```

**Cursor setup**

Use the same HTTP URL in Cursor's MCP settings and name the server `apify`.

**VS Code setup**

Add the same HTTP MCP server URL through your MCP-compatible VS Code extension or workspace configuration.

Example prompts:

- “Look up Colorado entity ID 20241583107 and summarize its current public registry facts.”
- “Export up to 25 good-standing businesses formed in Colorado Springs since 2026-07-01.”
- “Find Colorado entities whose registered name contains APIFY and return their filing-history links.”

Treat agent-generated interpretations as assistance, not legal or compliance conclusions.

### Pagination, retries, and performance

The Actor requests up to 1,000 rows per API page and stops as soon as `maxItems` unique records have been saved.

It retries network errors, rate limits, and temporary server failures up to three times with exponential backoff and jitter.

It does not retry malformed input, stable client errors, unexpected response formats, or schema bugs.

The implementation uses a direct HTTP API and requires no proxy configuration.

A 256 MB memory allocation is normally sufficient for the bounded page size.

### Limits and source freshness

- Maximum output is 10,000 entities per run.
- At least one search filter is required to prevent accidental full-registry exports.
- Name and agent searches are substring matches.
- City, status, and type filters are exact after case normalization.
- Entity type values are source codes, not expanded legal advice.
- The open dataset controls update timing and field availability.
- A filing-history URL is provided, but filing transactions are not copied into the default entity row.
- This Actor does not scrape documents, images, certificates, or paid filings.
- This Actor does not infer owners, beneficial owners, licenses, or good reputation.

### Empty results and errors

A successful run with zero records means no current source row matched all supplied filters.

If a known entity is missing:

1. verify that the ID contains digits only;
2. remove other filters that may exclude it;
3. try the exact ID in the official business search;
4. check whether the open dataset is temporarily delayed.

A failed run preserves a non-zero status and logs the validation or upstream error.

### Data quality tips

Use entity IDs instead of names when you need deterministic lookup.

Store the original `entityType` code rather than guessing a legal structure.

Expect address capitalization and city formatting to reflect source data.

Do not assume all registered agents are people; `organizationName` may be the only name field.

For time-sensitive verification, follow the source links and review the live official record.

### Responsible and legal use

Colorado business registration records are public government data, but public availability does not remove all obligations.

Use the data for lawful purposes and follow applicable privacy, consumer-protection, anti-discrimination, marketing, and record-retention rules.

Do not use the Actor to harass registered agents or individuals whose addresses appear in public filings.

Do not represent the output as legal advice, certification, sanctions screening, ownership proof, or a complete due-diligence decision.

Review the source's terms and attribute Colorado Open Data where your use requires it.

### Troubleshooting

**The run says that a search filter is required.**

Add `searchTerms`, `entityIds`, a status/type/city filter, `agentName`, or a formation-date bound.

**The API returned HTTP 429 or 5xx.**

The Actor retries temporary failures automatically. If all attempts fail, wait before rerunning rather than starting many concurrent runs.

**I received fewer records than `maxItems`.**

`maxItems` is a ceiling. The source may have fewer rows matching the combined filters.

**A field is missing from one row.**

Source records are not uniform. Optional addresses, agent components, and formation fields are omitted when unavailable.

**Can I search filing text?**

No. This Actor searches current business entity records and provides a filing-history API link for each entity.

### FAQ

**Is this an official Colorado government Actor?**

No. It is an independent Apify Actor that reads the official public Colorado Open Data API.

**Does it need a Colorado SOS account?**

No. The selected open-data endpoint is keyless.

**Does it support fuzzy company matching?**

It supports case-insensitive substring matching, not similarity scoring or identity resolution.

**Can it find newly formed businesses?**

Yes. Set `formedFrom`, optionally add a city/status/type filter, and sort by `formationDateDesc`.

**Does it monitor changes automatically?**

Apify can schedule runs, but change comparison belongs in your downstream database or automation.

**Are results complete in real time?**

No. Results reflect the open dataset at retrieval time and may lag the live filing system.

**Are registered-agent fields always present?**

No. The Actor returns them only when included in the source row.

**What identifies a duplicate?**

The Actor deduplicates rows by `entityId` within each run.

### Related Automation Lab Actors

Use [SEC EDGAR Filings Scraper](https://apify.com/automation-lab/sec-edgar-filings-scraper) when you need US federal public-company filing data rather than Colorado state registration records.

Use [Delaware Corporations Search Scraper](https://apify.com/automation-lab/delaware-corporations-search-scraper-v2) for comparable official state-registry checks in Delaware.

Choose this Actor when the job is a focused, official Colorado business-entity lookup or recurring Colorado registry export.

# Actor input Schema

## `searchTerms` (type: `array`):

Return entities whose registered name contains any term (case-insensitive).

## `entityIds` (type: `array`):

Look up exact Colorado Secretary of State entity identifiers. Digits only.

## `statuses` (type: `array`):

Optional exact status filters, such as Good Standing or Delinquent.

## `entityTypes` (type: `array`):

Optional exact Colorado entity type codes, such as DLLC or DPC.

## `principalCities` (type: `array`):

Optional exact principal-address city filters (case-insensitive).

## `agentName` (type: `string`):

Match a registered agent's first, middle, last, or organization name.

## `formedFrom` (type: `string`):

Include entities formed on or after this date (YYYY-MM-DD). Useful for recurring new-registration checks.

## `formedTo` (type: `string`):

Include entities formed on or before this date (YYYY-MM-DD).

## `sortBy` (type: `string`):

Choose a stable result order.

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

Stop after this many matching, unique entity records.

## Actor input object example

```json
{
  "searchTerms": [
    "APIFY"
  ],
  "sortBy": "entityNameAsc",
  "maxItems": 20
}
```

# Actor output Schema

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

Dataset containing all matching entity records.

# 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 = {
    "searchTerms": [
        "APIFY"
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/colorado-entity-search-scraper").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 = {
    "searchTerms": ["APIFY"],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/colorado-entity-search-scraper").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 '{
  "searchTerms": [
    "APIFY"
  ],
  "maxItems": 20
}' |
apify call automation-lab/colorado-entity-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/colorado-entity-search-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/xW5F3ALElbMdiJcas/builds/8eOOLYVYny5Iwmd4s/openapi.json