NY APIappext20.dos.ny.gov ↗
Search New York State UCC filings by debtor name or filing number. Retrieve lien details, parties, filing history, and status via 3 structured endpoints.
What is the NY API?
This API provides programmatic access to New York State Uniform Commercial Code (UCC) public filings through 3 endpoints. Use search_by_debtor_name to find filings tied to an individual or organization, search_by_filing_number to look up a specific lien, and get_filing_detail to retrieve the full record including all debtors, secured parties, and complete filing history with amendments and continuations.
curl -X GET 'https://api.parse.bot/scraper/bebb3602-31a1-4f72-83b5-8cc63386731c/search_by_filing_number?filing_number=201306030311234' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace appext20-dos-ny-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: NY UCC Filing Search — search filings, drill into detail."""
from parse_apis.appext20_dos_ny_gov_api import NYUCCFilings, DebtorType, SearchLogic, InputFormatInvalid
client = NYUCCFilings()
# Search for organization filings by name, cap total items.
for summary in client.filing_summaries.search_by_name(
debtor_type=DebtorType.ORGANIZATION,
organization_name="Chase",
search_logic=SearchLogic.STANDARD,
limit=5,
):
print(summary.lien_number, summary.debtor_name, summary.lien_status)
# Drill into the first hit's full detail via the summary→detail navigation.
hit = client.filing_summaries.search_by_name(
debtor_type=DebtorType.ORGANIZATION,
organization_name="Chase",
limit=1,
).first()
if hit is not None:
filing = hit.details()
print("Lien:", filing.lien_number, "Status:", filing.status, "Type:", filing.lien_type)
for debtor in filing.debtors:
print(" Debtor:", debtor.debtor_name, debtor.debtor_address)
for party in filing.secured_parties:
print(" Secured party:", party.secured_party_name, party.secured_party_address)
for event in filing.filing_history:
print(" History:", event.filing_number, event.filing_type, event.filing_action)
# Search by filing number directly; handle invalid input gracefully.
try:
result = client.filing_summaries.search_by_number(
filing_number="201306030311234", limit=1
).first()
except InputFormatInvalid as e:
print("Bad filing number format:", e.message)
result = None
if result is not None:
detail = result.details()
print("Direct lookup:", detail.lien_number, detail.status)
print("exercised: search_by_name / search_by_number / details")
Search UCC filings by lien/filing number. Returns matching filings with summary information including lien number, debtor name, filing date, lapse date, and status. Each result includes a lien_id that can be passed to get_filing_detail for full information. One page of up to 10 results is returned per call.
| Param | Type | Description |
|---|---|---|
| filing_numberrequired | string | The UCC filing/lien number to search for (e.g. '201306030311234'). |
{
"type": "object",
"fields": {
"filings": "array of filing summary objects with lien_number, lien_id, serial_number, lien_subtype, debtor_name, debtor_address, debtor_type, filing_date, lapse_date, lien_status",
"total_pages": "integer, total number of pages",
"total_records": "integer, total number of matching filings"
},
"sample": {
"data": {
"filings": [
{
"lien_id": "1936661",
"lapse_date": "1/1/9999 12:00:00 AM",
"debtor_name": "CHASE",
"debtor_type": "Organization",
"filing_date": "6/3/2013 4:30:00 PM",
"lien_number": "201306030311234",
"lien_status": "Active",
"lien_subtype": null,
"serial_number": null,
"debtor_address": "3415 VISION DRIVE, COLUMBUS, OH, 43219 - 6009, USA"
}
],
"total_pages": 1,
"total_records": 1
},
"status": "success"
}
}About the NY API
Searching UCC Filings
The search_by_filing_number endpoint accepts a lien/filing number (e.g. 201306030311234) and returns matching filing summaries. Each result includes lien_number, lien_id, debtor_name, debtor_address, debtor_type, filing date, lapse date, and current status. The lien_id returned here is the key input for fetching full detail records.
The search_by_debtor_name endpoint supports searching by individual or organization. For individuals, supply last_name (required), with optional first_name and middle_name to narrow results. For organizations, provide organization_name. The debtor_type parameter switches between modes, and search_logic controls match behavior. Results are paginated at 10 per page; the page parameter retrieves subsequent pages, and total_records and total_pages tell you how many results exist.
Filing Detail
get_filing_detail takes a lien_id from any search result and returns the complete filing record. Response fields include lien_type, lien_number, serial_number, date_filed, lapse_date, status, and subtype. The debtors array provides per-debtor fields including organization_id, organization_type, and organization_jurisdiction. The secured_parties array lists each party's name, address, and type. The filing_history array covers the full lifecycle — initial filing plus any amendments, continuations, and terminations — each entry carrying filing_number, filing_type, filing_action, filing_status, and date_filed.
Coverage and Scope
All data reflects New York State UCC filings held by the NY Department of State. Filing numbers follow the state's assigned format. Lapse dates reflect the standard five-year UCC lien term unless a continuation has been filed, which will appear in the filing_history array.
The NY API is a managed, monitored endpoint for appext20.dos.ny.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when appext20.dos.ny.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official appext20.dos.ny.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Verify whether a business or individual has active UCC liens before extending credit
- Monitor lien status changes — active vs. inactive — for due diligence workflows
- Retrieve all secured parties for a debtor to map creditor exposure
- Track filing history including amendments and terminations for a specific lien
- Build a lien search tool for commercial real estate or asset-based lending platforms
- Cross-reference organization_id and organization_jurisdiction fields with other business registry data
- Identify upcoming lapse dates across a portfolio of tracked lien numbers
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.