# New York State Tax Warrants - Business Tax Liens (`j0401/ny-tax-warrants`) Actor

New York State tax warrants (public open data, 667k records): tax liens filed by NYS Taxation & Finance with the Dept. of State, with their satisfactions, vacates and amendments. Search by debtor name across all named debtors, amount, county, state or date. For KYB, credit and vendor-risk screening.

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

## Pricing

from $0.03 / 1,000 new york tax warrant 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

## New York State Tax Warrants - Business Tax Liens

The New York State Department of Taxation and Finance files **tax warrants** - the state's recorded lien for unpaid tax - with the NYS Department of State, and publishes the register as **open data**. This actor turns it into a **charged-per-record lookup and screening tool**.

**Built for:** KYB and vendor-risk screening - checking whether a business or individual carries an unpaid New York State tax lien, sizing the exposure, and confirming whether a lien has been satisfied or vacated. Used for credit and underwriting decisions, M\&A and title diligence, and accounts-receivable risk.

### What it covers

**667,922 warrant records** (open data, continuously refreshed):

| Status | Meaning | Records |
|---|---|---|
| `Added` | warrant filed | 424,333 |
| `Closed` | satisfied or vacated | 243,398 |
| `Updated` | amended | 191 |

Each record carries the **warrant id**, the **status** (and its meaning), up to **four named debtors** with their address, city, state, ZIP, county and country, the **filed amount**, and the full lifecycle of dates: **filed**, **satisfaction**, **vacate**, **amend** and **expiration**. Dates come through as clean ISO (`YYYY-MM-DD`).

> **Two things this file is, and one it is not.** It is the **business / tax** debtor register - unpaid income, sales and corporate tax warrants recorded as public liens, the record a credit or KYB screen runs against. It is a **windowed** feed (the state's published dataset begins 7/1/2025), so it carries recent filings rather than the complete historical lien book. And because the file records the **lifecycle event**, the same warrant can appear more than once as its status changes - `warrant_id` is not unique per row; the **status** is what tells you whether the lien is live (`Added`) or cleared (`Closed`).
>
> It is **not** NY's child-support warrant file - a different table of individuals' family-support debt that this actor deliberately does not carry.

### Typical questions

- "Does **this company or person** have an unpaid New York tax lien?"
- "Show every **added (live)** warrant for this debtor name."
- "Which warrants have been **satisfied or vacated**?"
- "List warrants **filed in the last 90 days**."
- "Find warrants of **$100,000 or more** for a name."
- "How are NY tax warrants **distributed by debtor state and filing year**?"

### Inputs

| Input | What it does |
|---|---|
| `debtorName` | substring match across **all four** named debtor columns |
| `statusCode` | Added = filed (live lien), Closed = satisfied/vacated, Updated = amended |
| `state` / `city` / `countyCode` / `countryCode` | debtor location |
| `minAmount` / `maxAmount` | warrant filed-amount range (USD) |
| `filedFrom` / `filedTo` | warrant filed-date window (YYYY-MM-DD) |
| `recentDays` | warrants filed within the last N days (0 = off) |
| `mode` / `groupBy` | `rows` for records, or `aggregate` for one row per group (status / state / county / year) |
| `maxResults` | cap records (default 50) |

**Default run = the newest filings.** Add a `debtorName` filter or a date window to narrow; or set `mode=aggregate` for a whole-register rollup.

### Example inputs

**Screen a debtor name** - matches any of the four named debtors.

```json
{ "debtorName": "CONSTRUCTION LLC", "maxResults": 10 }
```

**Only live liens** - `statusCode=Added` returns warrants that have been filed and not yet cleared.

```json
{ "statusCode": "Added", "maxResults": 10 }
```

**Large, recent warrants** - filings of $100,000+ in the last 90 days.

```json
{ "minAmount": 100000, "recentDays": 90, "maxResults": 10 }
```

**The status mix** - one summary row per status, across the register.

```json
{ "mode": "aggregate", "groupBy": "statusCode" }
```

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

The warrant register is a **667,922-row** statewide filing record, and a name
screen has to reach every one of the four named debtors on a warrant, not just
the first. Every pull is integrity-checked against the register's known shape (a
total-count floor, a freshness probe on the newest filed timestamp, key-column
coverage), so a degraded or schema-changed source **fails loudly** instead of
returning bad rows.

### Example output

**`debtorName=CONSTRUCTION`** - one matching warrant:

```json
{
 "platform": "ny-tax-warrants",
 "source": "ny-tax-warrants",
 "dataState": "NY",
 "mode": "rows",
 "recordType": "warrant",
 "warrantId": "E-064113702-W001-9",
 "statusCode": "Added",
 "statusMeaning": "Added",
 "debtorName1": "CONSTRUCTION RESOURCES CORP. OF NEW YORK",
 "debtorName2": "",
 "debtorName3": "",
 "debtorName4": "",
 "debtorAddress1": "",
 "debtorAddress2": "221 HUNTER AVE",
 "city": "STATEN ISLAND",
 "state": "NY",
 "zipCode": "103063445",
 "countyCode": "RICHMOND",
 "countryCode": "US",
 "filedAmount": "51767.54",
 "filedDate": "2026-09-30",
 "satisfactionDate": "",
 "vacateDate": "",
 "amendDate": "",
 "expirationDate": "",
 "filedTimestamp": "2026-09-30",
 "sourceUrl": "https://www.tax.ny.gov/warrants/lookup.html?document=e-064113702-w001.pdf",
 "sourceUpdatedAt": "2026-10-05",
 "groupKey": "",
 "groupCount": "",
 "groupBy": ""
}
```

**`mode=aggregate`, `groupBy=state`** - warrants by debtor state (top):

```
NY    579,590
NJ     22,880
FL     11,417
CA      7,021
CT      6,059
```

### Source

- [New York State Tax Warrants - Open Data](https://data.ny.gov/Government/New-York-State-Tax-Warrants-Beginning-7-1-2025/v7ua-z23v) - the official public dataset this actor reads (NYS Dept. of Taxation and Finance, filed with the NYS Dept. of State).

# Actor input Schema

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

Substring match across all named debtors (a warrant can name up to four). E.g. "CONSTRUCTION", "SMITH". Names are businesses and individuals with an unpaid NYS tax warrant.

## `statusCode` (type: `string`):

Added = warrant filed (live lien), Closed = satisfied or vacated, Updated = amended. Blank = all. Values are the source's own full words.

## `state` (type: `string`):

Two-letter debtor state, exact match (e.g. "NY").

## `city` (type: `string`):

Substring match on the debtor city.

## `countyCode` (type: `string`):

Substring match on the NY county code.

## `countryCode` (type: `string`):

Substring match on the debtor country code (e.g. "US").

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

Lowest filed warrant amount in USD.

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

Highest filed warrant amount in USD.

## `filedFrom` (type: `string`):

Earliest warrant filed date, YYYY-MM-DD (inclusive).

## `filedTo` (type: `string`):

Latest warrant filed date, YYYY-MM-DD (inclusive).

## `recentDays` (type: `integer`):

Only warrants filed within the last N days. 0 = off. Do not combine with filedFrom.

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

rows = matching warrant records; aggregate = one summary row per group with a count.

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

Dimension for aggregate mode. statusCode -> added / closed / updated; state -> debtor-state mix; filedYear -> warrants by filing year.

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

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

## Actor input object example

```json
{
  "debtorName": "",
  "statusCode": "",
  "state": "",
  "city": "",
  "countyCode": "",
  "countryCode": "",
  "filedFrom": "",
  "filedTo": "",
  "recentDays": 0,
  "mode": "rows",
  "groupBy": "statusCode",
  "maxResults": 50
}
```

# Actor output Schema

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

New York State tax warrant 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/ny-tax-warrants").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/ny-tax-warrants").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/ny-tax-warrants --silent --output-dataset

```

## MCP server setup

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

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/AyizcaCLujLdGXhUk/builds/1W7cGz1y1YQvsJ6Sb/openapi.json