# NYC UCC Liens & Federal Tax Liens - ACRIS Personal Property (`j0401/nyc-acris`) Actor

NYC ACRIS personal-property recordings (4.55M documents): UCC financing statements, continuations, assignments and terminations plus federal tax liens, each with its debtor and secured-party names. Screen a company for liens by name, look up one document, or aggregate by type, borough or year.

- **URL**: https://apify.com/j0401/nyc-acris.md
- **Developed by:** [Wenhao Yang](https://apify.com/j0401) (community)
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.03 / 1,000 nyc acris lien records

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

## NYC UCC Liens & Federal Tax Liens - ACRIS Personal Property

Every recorded UCC financing statement and federal tax lien filed in New York
City: **4,552,980 documents** from the city's ACRIS personal-property register,
joined to their **11M party rows** so a filing carries its debtor and
secured-party names.

This is the lien and KYB surface - the thing a credit, onboarding or
vendor-risk check reaches for. Not real property (that is the separate ACRIS
Real Property dataset).

### Low cost

**From $0.00005 per record, down to $0.00003 at Gold.** Pay only for the records
you actually receive - the whole register stays queryable, you are never billed
for the scan behind it.

### Screen a company for liens

`mode=debtor` returns every filing naming a debtor (or any party), each with the
document's type, date, borough and amount:

```json
{ "mode": "debtor", "debtorName": "ACME", "maxResults": 50 }
```

Set `exactName=true` to match the whole name (`"ACME CORP"`); by default it
matches a **name prefix**, which is what the source's index is fast on. Narrow
to a role with `partyRole` (1 = Debtor, 2 = Secured Party, 3 = Third Party).

### What is in a filing

- **Type** - decoded from the source's code: `INIT` / `INIC` initial UCC1,
  `CONT` continuation, `TERM` termination, `ASGN` assignment, `AMND` amendment,
  `RLSE` release, `FL` an IRS federal tax lien, `FTL` other federal lien, `RFL`
  release of federal lien, plus the amendment / withdrawal / partial-release and
  bankruptcy variants (29 codes in all).
- **Document amount** - the lien amount where stated. Note most UCC filings
  carry `0` (a UCC1 states no amount); federal tax liens carry the figure.
- **`goodThroughDate`** - the UCC continuation deadline, i.e. whether the filing
  is still live.
- **Borough** - decoded (1 = Manhattan  5 = Staten Island).
- **Collateral** - decoded (Fixture Filing, Cooperative, Manufactured Housing ).

### Search documents

- **Type** - `docType="FL"` (IRS liens), `"TERM"` (terminations).
- **Where** - `borough` (1-5).
- **When** - `dateFrom` / `dateTo` (ISO).
- **Amount** - `minAmount` / `maxAmount`.
- **Collateral** - `collateral` (F / C / A ).

```json
{ "docType": "FL", "dateFrom": "2026-01-01", "borough": "1", "maxResults": 50 }
```

### Look up one document

`mode=document` returns the document plus every party on it (name, role,
address) - a `crfn` is accepted as well as a `documentId`:

```json
{ "mode": "document", "crfn": "2026000219331" }
```

### Or roll it up

`mode=aggregate` returns one count row per group - **document type**,
**borough**, **collateral type** or **recording year**. Every group comes back;
this mode is not cut off by `maxResults`.

```
INIT    1,008,416
TERM      990,506
FL        377,567
CONT      248,045
ASGN      235,488
```

### Example output

**One debtor's filing** - `mode=debtor`:

```json
{
 "platform": "nyc-acris",
 "documentId": "2026080400059001",
 "crfn": "2026000219331",
 "docType": "TERM",
 "docTypeDescription": "UCC3 TERMINATION",
 "recordedDatetime": "2026-08-04",
 "borough": "Manhattan",
 "documentAmount": "0",
 "collateralDescription": "FIXTURE FILING",
 "partyRole": "Debtor",
 "partyName": "DEMETRIUS, JANE",
 "partyCity": "QUEENS",
 "partyState": "NY",
 "partyZip": "11429"
}
```

### Notes on the data, from the source

- **One row = one recorded document** (or, in `document` / `debtor` mode, one
  (document, party) pair). `document_id` is essentially unique on the master.
- **The debtor / secured-party names are in the parties table**, not the
  document row - this actor joins them, which is what makes it a screening tool
  rather than a bare document list.
- **`document_amt` is `0` on most UCC rows** - a UCC financing statement states
  no amount. Do not read the column as a transaction value.
- **`recorded_borough` and `doc_type` are codes** in the source; both are decoded
  on output and shown as readable text alongside the code.
- **Name search is prefix-based by default.** The parties table is 11M rows and
  a leading-wildcard contains-match is a full scan the source times out on;
  prefix and exact matches are index-fast. Use `exactName=true` for a whole-name
  match.
- **The register is refreshed daily, not in real time** - ACRIS is a
  recording-once archive, so each record's `recordedDatetime` is its own filing
  date and the newest `recordedDatetime` in a result set is how current the
  data is.

# Actor input Schema

## `mode` (type: `string`):

search = filter recorded documents. document = one document + its parties (needs documentId or crfn). debtor = documents naming a debtor (needs debtorName) - the KYB screen. aggregate = one row per group. Blank auto-routes.

## `debtorName` (type: `string`):

Party name for mode=debtor. Matches a name PREFIX by default (e.g. "ACME" matches ACME CORP, ACME LLC). Names are stored uppercase.

## `exactName` (type: `boolean`):

With mode=debtor, match the name exactly instead of by prefix (e.g. "ACME CORP").

## `partyRole` (type: `string`):

With mode=debtor: 1 = Debtor (default usage), 2 = Secured Party, 3 = Third Party. Blank = any role.

## `documentId` (type: `string`):

With mode=document: the ACRIS document id, e.g. "2026080400059001".

## `crfn` (type: `string`):

With mode=document: the City Register File Number, e.g. "2026000219331".

## `docType` (type: `string`):

Document type code. INIT/INIC = initial UCC1, CONT = continuation, TERM = termination, ASGN = assignment, AMND = amendment, FL = IRS federal lien, FTL = other federal lien, RFL = release. Blank = all.

## `borough` (type: `string`):

Recording borough code: 1 = Manhattan, 2 = Bronx, 3 = Brooklyn, 4 = Queens, 5 = Staten Island. Blank = all.

## `collateral` (type: `string`):

UCC collateral code: F = Fixture Filing, C = Cooperative, A = Cooperative with addendum, R = crops/timber, M = manufactured housing, O = other. Blank = all.

## `rpttlNumber` (type: `string`):

Exact RPTTL number (links a personal-property filing to a tax lot).

## `dateFrom` (type: `string`):

Recording date lower bound, ISO YYYY-MM-DD (e.g. "2026-01-01").

## `dateTo` (type: `string`):

Recording date upper bound, ISO YYYY-MM-DD (e.g. "2026-12-31").

## `minAmount` (type: `number`):

Minimum document amount (USD). Note: most UCC filings state 0; federal liens carry the amount.

## `maxAmount` (type: `number`):

Maximum document amount (USD).

## `aggregate` (type: `boolean`):

When on, returns one summary record per group with count, instead of documents.

## `groupBy` (type: `string`):

docType -> UCC vs federal-lien mix; borough -> recording geography; collateral -> collateral type; recordYear -> filings per year.

## `maxResults` (type: `integer`):

Cap the number of records pushed (0 = a default of 50).

## Actor input object example

```json
{
  "exactName": false,
  "aggregate": false,
  "groupBy": "docType",
  "maxResults": 50
}
```

# Actor output Schema

## `recordsUrl` (type: `string`):

NYC ACRIS UCC & federal tax lien records - as JSON

## `datasetUrl` (type: `string`):

No description

## `runUrl` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("j0401/nyc-acris").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("j0401/nyc-acris").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 j0401/nyc-acris --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,j0401/nyc-acris"
        }
    }
}
```

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/viYtiiLiKaRyjPiMe/builds/Xp0djWdmjuHYxU3zv/openapi.json