# UCC Borrower Portfolio Monitor (`gourmet_haircut_v6i/ucc-borrower-portfolio-monitor`) Actor

Organization-only UCC monitoring for Connecticut and Colorado using evidence-feed events.

- **URL**: https://apify.com/gourmet\_haircut\_v6i/ucc-borrower-portfolio-monitor.md
- **Developed by:** [Pedro Dantas](https://apify.com/gourmet_haircut_v6i) (community)
- **Categories:** Business, Automation
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

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

## UCC Borrower Portfolio Monitor

Monitor organization borrowers for new UCC filing lifecycle events in **Connecticut** and **Colorado** using official public data sources.

This Actor is designed for business-to-business monitoring workflows where you already know the organization names you want to watch. It is an evidence feed, not a certified UCC search, legal opinion, perfection determination, consumer report, or FCRA product.

### What it does

For each organization borrower in your input, the Actor:

1. reads recent official UCC data for the selected state;
2. matches organization names conservatively using exact normalized legal names or explicit aliases;
3. classifies supported lifecycle events such as initial financing statements, amendments, continuations, and terminations;
4. stores a persistent baseline for your `monitorKey`;
5. emits only newly observed matched events after the baseline is established.

Supported states:

- **Connecticut (CT)**
- **Colorado (CO)**

Individuals and consumer-debt monitoring are intentionally outside this Actor's contract.

### Quick start

Use a stable `monitorKey` for the portfolio you want to monitor.

```json
{
  "monitorKey": "synthetic-demo-portfolio",
  "borrowers": [
    {
      "state": "CT",
      "legalName": "R21 SYNTHETIC DEMO BORROWER LLC",
      "externalId": "demo-001",
      "aliases": [],
      "city": "HARTFORD",
      "zip": "06103"
    }
  ],
  "baselineMode": "storeOnly",
  "lookbackDays": 7
}
```

The example above is synthetic and is not intended to identify a real organization.

### Input

#### `monitorKey`

A stable identifier for the monitored portfolio. It is used to derive the Actor's persistent state namespace.

Reusing the same `monitorKey` allows later runs to compare against previously observed events.

#### `borrowers[]`

One or more organization borrowers.

Required per borrower:

- `state`: `CT` or `CO`
- `legalName`: organization legal name

Optional:

- `externalId`: your own stable identifier
- `aliases[]`: explicit alternative organization names accepted for exact normalized matching
- `city`
- `zip`

City and ZIP are supporting evidence only. They do not enable fuzzy matching.

#### `baselineMode`

- `storeOnly` — recommended default. The first successful run stores the baseline without emitting historical snapshot events.
- `emitSnapshot` — the first successful run emits the matched snapshot and stores it as the baseline.

#### `lookbackDays`

Number of days in the bounded overlap window used for official-source reads.

- minimum: 1
- maximum: 30
- default: 7

### Output

#### Dataset events

When new matched events are found, the default dataset contains final event records such as:

- `eventId`
- `externalId`
- `state`
- `legalName`
- `eventType`
- `filingNumber`
- `filingDate`
- `lapseDate`
- `securedParty`
- `sourceUrl`
- `observedAt`
- `match`
- `sourceEvidence`

Event IDs are deterministic and borrower-specific.

#### Run summary

The default key-value store record `OUTPUT` contains:

- `monitorKey`
- `status`
- `borrowerCount`
- `emittedEventCount`
- `observedAt`

Possible status values:

- `SUCCESS`
- `PARTIAL`
- `FAILED`

A `PARTIAL` or `FAILED` run does **not** advance persistent monitoring state.

### Matching policy

Matching is deliberately conservative.

The Actor accepts:

- exact normalized legal-name matches;
- explicit aliases supplied by you.

It does **not** automatically accept:

- fuzzy names;
- phonetic similarity;
- edit-distance matches;
- inferred aliases.

An exact name with incomplete or mismatching city/ZIP evidence can be surfaced for review rather than silently promoted to a stronger match.

### Official data sources

#### Connecticut

Official Connecticut UCC dataset:

- dataset ID: `xfev-8smz`
- source: Connecticut Secretary of State / data.ct.gov

The Actor processes the supported OFS subset conservatively.

#### Colorado

Official Colorado datasets:

- filings: `wffy-3uut`
- debtors: `8upq-58vz`
- source: Colorado Department of State / data.colorado.gov

For amendments, the Actor resolves the filing lifecycle back to the original filing before joining organization debtors.

### Persistent monitoring

State is stored in a named key-value store derived from `monitorKey`.

The raw `monitorKey` is not exposed in the storage name.

Successful runs can advance the baseline. `PARTIAL` and `FAILED` runs do not mutate the prior monitoring state.

### Important limitations

This Actor:

- monitors **organizations only**;
- currently supports **CT and CO only**;
- is not a certified UCC search;
- does not determine lien priority, perfection, enforceability, or legal effect;
- is not legal advice;
- is not intended for consumer reporting or FCRA use;
- does not use fuzzy auto-matching;
- depends on the availability and completeness of the official public datasets.

For decisions with legal or lending consequences, verify the underlying official records and use qualified professional review when appropriate.

### Data handling

The Actor reads official public filing data and stores monitoring state needed for deduplication under your `monitorKey`.

Avoid placing secrets or unnecessary personal information in `monitorKey`, borrower names, aliases, or other input fields.

### Current release scope

This release focuses on a small, auditable monitoring core:

- Connecticut + Colorado;
- organization borrowers;
- exact/explicit-alias matching;
- persistent baseline and deduplication;
- evidence-rich event output.

Additional states or broader matching behavior should be treated as separate capabilities rather than assumed from the current release.

# Actor input Schema

## `monitorKey` (type: `string`):

Stable portfolio identity used to derive the monitor persistence namespace.

## `borrowers` (type: `array`):

Organization borrowers to monitor. Individuals and consumer use are outside this contract.

## `baselineMode` (type: `string`):

On the first successful observation, store silently or emit the matched snapshot.

## `lookbackDays` (type: `integer`):

Bounded overlap window used for official-source incremental reads.

## Actor input object example

```json
{
  "baselineMode": "storeOnly",
  "lookbackDays": 7
}
```

# Actor output Schema

## `events` (type: `string`):

Final emitted organization-borrower events in the default dataset.

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

Summary metadata stored under OUTPUT in the default key-value store.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

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

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("gourmet_haircut_v6i/ucc-borrower-portfolio-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("gourmet_haircut_v6i/ucc-borrower-portfolio-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call gourmet_haircut_v6i/ucc-borrower-portfolio-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gourmet_haircut_v6i/ucc-borrower-portfolio-monitor"
        }
    }
}
```

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/BIdtnralDDRAu1Zep/builds/IkuKjNwL4DnbPVBjn/openapi.json