Invoke the UCC debtor API

The /ucc/debtor endpoint lets you search UCC (Uniform Commercial Code) lien records filed against debtors (i.e., businesses). This guide walks through increasingly sophisticated ways to call the endpoint, starting with a basic URL lookup and ending with multi-filter queries, pagination, and a Python automation script.

Prerequisites

A valid LeadX API key
A terminal or API client (e.g., Postman) for running cURL commands
Python 3.7+ for the scripted examples (optional)

Example 1: Look up a company by URL

The simplest call passes a single company URL. This returns all UCC filings where that company is listed as the debtor.

cURL
Python

Terminal

curl -X POST "https://api.leadx.com/v1/ucc/debtor" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "acmeplumbing.com"}'

requests

import requests

url = "https://api.leadx.com/v1/ucc/debtor"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {"url": "acmeplumbing.com"}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

A successful response includes a records array of UCC filings and pagination metadata:

200 - Successful response

{
  "success": true,
  "records": [
    {
      "company_name": "ACME PLUMBING LLC",
      "ucc_id": "12345678-NJ",
      "ucc_number": "12345678",
      "ucc_type": "UCC1",
      "date_filed": "2023-01-15 00:00:00.000000",
      "date_expired": "2028-01-15 00:00:00.000000",
      "secured_party": "First National Bank",
      "secured_party_class": "Bank",
      "state": "NJ",
      "has_amendments": false,
      "has_continuation": false
    }
  ],
  "page_number": 1,
  "per_page": 50,
  "total_pages": 1,
  "total_records": 1
}

You can also look up debtors by company_id, phone, name, address, or city instead of url. At least one search parameter is required.

Example 2: Look up by company name

If you don’t have a URL, you can search by company name. The name parameter supports fuzzy matching and accepts a single string or a list.

cURL
Python

Terminal

curl -X POST "https://api.leadx.com/v1/ucc/debtor" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Home Depot"}'

requests

import requests

url = "https://api.leadx.com/v1/ucc/debtor"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {"name": "Home Depot"}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

To search for multiple companies in one request, pass an array:

cURL
Python

Terminal

curl -X POST "https://api.leadx.com/v1/ucc/debtor" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": ["Home Depot", "Lowes"]}'

requests

import requests

url = "https://api.leadx.com/v1/ucc/debtor"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {"name": ["Home Depot", "Lowes"]}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

Example 3: Filter by collateral and amendments

You can narrow results using boolean filters. This example finds filings that include collateral descriptions and have amendments:

cURL
Python

Terminal

curl -X POST "https://api.leadx.com/v1/ucc/debtor" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "acmeplumbing.com",
    "has_collateral": true,
    "has_amendment": true
  }'

requests

import requests

url = "https://api.leadx.com/v1/ucc/debtor"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "url": "acmeplumbing.com",
    "has_collateral": True,
    "has_amendment": True,
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

Each matching record includes the collateral text and an amendments array with details about each amendment filing:

200 - Successful response (partial)

{
  "success": true,
  "records": [
    {
      "company_name": "ACME PLUMBING LLC",
      "collateral": "All accounts; inventory; equipment; fixtures; instruments...",
      "has_collateral": true,
      "has_amendments": true,
      "amendments": [
        {
          "amendment_type": "Assignment",
          "date_filed": "2024-03-15T10:00:00",
          "secured_party": "Second National Bank",
          "ucc_number": "2024-98765432"
        }
      ]
    }
  ],
  "page_number": 1,
  "per_page": 50,
  "total_pages": 1,
  "total_records": 1
}

Example 4: Filter by industry and date range

Combine industry classification filters with date filters to find filings in specific sectors. Date filters support absolute formats (YYYY-MM-DD) and relative durations (6 months, 1 year).

cURL
Python

Terminal

curl -X POST "https://api.leadx.com/v1/ucc/debtor" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "Construction",
    "date_filed": "1 year",
    "has_collateral": true
  }'

requests

import requests

url = "https://api.leadx.com/v1/ucc/debtor"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "industry": "Construction",
    "date_filed": "1 year",
    "has_collateral": True,
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

This returns all construction-industry debtor filings made within the last year that include collateral. You can also filter by NAICS code, SIC code, or their descriptions:

cURL
Python

Terminal

curl -X POST "https://api.leadx.com/v1/ucc/debtor" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "naics_code": "238220",
    "date_filed": "2024-01-01",
    "state_filing": "CA"
  }'

requests

import requests

url = "https://api.leadx.com/v1/ucc/debtor"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "naics_code": "238220",
    "date_filed": "2024-01-01",
    "state_filing": "CA",
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

Example 5: Use pagination for large result sets

When a query returns many records, use page and per_page to iterate through results. The maximum per_page value is 50.

cURL
Python

Terminal

curl -X POST "https://api.leadx.com/v1/ucc/debtor" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "Construction",
    "page": 1,
    "per_page": 50
  }'

requests

import requests

url = "https://api.leadx.com/v1/ucc/debtor"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "industry": "Construction",
    "page": 1,
    "per_page": 50,
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

The response metadata tells you how many pages exist:

Pagination metadata

{
  "page_number": 1,
  "per_page": 50,
  "total_pages": 42,
  "total_records": 4165
}

Request subsequent pages by incrementing the page value:

cURL
Python

Terminal

curl -X POST "https://api.leadx.com/v1/ucc/debtor" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "Construction",
    "page": 2,
    "per_page": 50
  }'

requests

import requests

url = "https://api.leadx.com/v1/ucc/debtor"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "industry": "Construction",
    "page": 2,
    "per_page": 50,
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

If page exceeds total_pages, the records array will be empty. Values outside the 1-50 range for per_page will return a 422 validation error. See the pagination guide for more details.

Example 6: Combine multiple filters

All filter parameters are combined with AND logic — only records matching every filter are returned. This example finds recently modified filings for a specific lender with continuations:

cURL
Python

Terminal

curl -X POST "https://api.leadx.com/v1/ucc/debtor" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secured_party_company_id": "7KXRMB4DWQPCSXZNT9HJYF",
    "has_continuation": true,
    "modified_date": "30 days",
    "industry": ["Construction", "Manufacturing"],
    "per_page": 50,
    "page": 1
  }'

requests

import requests

url = "https://api.leadx.com/v1/ucc/debtor"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "secured_party_company_id": "7KXRMB4DWQPCSXZNT9HJYF",
    "has_continuation": True,
    "modified_date": "30 days",
    "industry": ["Construction", "Manufacturing"],
    "per_page": 50,
    "page": 1,
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

You can also exclude specific values from results using the exclude parameter:

cURL
Python

Terminal

curl -X POST "https://api.leadx.com/v1/ucc/debtor" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "Construction",
    "date_filed": "6 months",
    "exclude": {
      "url": ["example-exclude.com"],
      "phone": ["9876543210"]
    },
    "per_page": 50
  }'

requests

import requests

url = "https://api.leadx.com/v1/ucc/debtor"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "industry": "Construction",
    "date_filed": "6 months",
    "exclude": {
        "url": ["example-exclude.com"],
        "phone": ["9876543210"],
    },
    "per_page": 50,
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

Example 7: Filter by company size and filing count

Target companies by employee count, revenue, time in business, or number of UCC filings. Range filters accept a single number, a [min, max] array, or an object with min and max keys.

cURL
Python

Terminal

curl -X POST "https://api.leadx.com/v1/ucc/debtor" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "Manufacturing",
    "number_employees": {"min": 10, "max": 250},
    "company_filing_count": [2, 10],
    "annual_revenue": {"min": 1000000, "max": 50000000},
    "per_page": 50
  }'

requests

import requests

url = "https://api.leadx.com/v1/ucc/debtor"
headers = {
    "X-API-KEY": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "industry": "Manufacturing",
    "number_employees": {"min": 10, "max": 250},
    "company_filing_count": [2, 10],
    "annual_revenue": {"min": 1000000, "max": 50000000},
    "per_page": 50,
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
print(response.json())

The one_filing_per_debtor parameter is deprecated. Results are now always grouped by debtor, so this parameter is no longer needed and will be ignored if provided.

Example 8: Automate pagination with Python

This script iterates through all pages of a filtered query and collects every record into a single list.

ucc_debtor_search.py

import os
import requests

API_KEY = os.getenv("LEADX_API_KEY")
BASE_URL = "https://api.leadx.com/v1/ucc/debtor"
HEADERS = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}

def fetch_all_ucc_records(filters: dict, per_page: int = 100) -> list:
    """Fetch all UCC debtor records matching the given filters."""
    all_records = []
    page = 1

    while True:
        payload = {**filters, "page": page, "per_page": per_page}
        response = requests.post(BASE_URL, headers=HEADERS, json=payload)
        response.raise_for_status()
        data = response.json()

        records = data.get("records", [])
        all_records.extend(records)

        total_pages = data.get("total_pages", 1)
        print(f"Page {page}/{total_pages} — fetched {len(records)} records")

        if page >= total_pages:
            break
        page += 1

    return all_records


if __name__ == "__main__":
    filters = {
        "industry": "Construction",
        "date_filed": "6 months",
        "has_collateral": True,
        "state_filing": "CA"
    }

    records = fetch_all_ucc_records(filters, per_page=50)
    print(f"\nTotal records collected: {len(records)}")

    # Print a summary of each filing
    for r in records[:5]:
        print(f"  {r.get('company_name')} — {r.get('ucc_id')} — "
              f"Secured by: {r.get('secured_party', 'N/A')}")

Run the script:

Terminal

export LEADX_API_KEY="your_api_key_here"
python3 ucc_debtor_search.py

Example 9: Export results to CSV with Python

Build on the previous example to write filtered UCC records to a CSV file.

ucc_debtor_export.py

import os
import csv
import requests

API_KEY = os.getenv("LEADX_API_KEY")
BASE_URL = "https://api.leadx.com/v1/ucc/debtor"
HEADERS = {"X-API-KEY": API_KEY, "Content-Type": "application/json"}

CSV_FIELDS = [
    "company_name", "ucc_id", "ucc_type", "date_filed", "date_expired",
    "secured_party", "secured_party_class", "state", "industry",
    "has_collateral", "has_amendments", "has_continuation", "collateral"
]

def fetch_all_ucc_records(filters: dict, per_page: int = 50) -> list:
    """Fetch all UCC debtor records matching the given filters."""
    all_records = []
    page = 1

    while True:
        payload = {**filters, "page": page, "per_page": per_page}
        response = requests.post(BASE_URL, headers=HEADERS, json=payload)
        response.raise_for_status()
        data = response.json()

        records = data.get("records", [])
        all_records.extend(records)

        total_pages = data.get("total_pages", 1)
        print(f"Page {page}/{total_pages} — fetched {len(records)} records")

        if page >= total_pages:
            break
        page += 1

    return all_records

def export_to_csv(records: list, output_file: str):
    """Write UCC records to a CSV file."""
    with open(output_file, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=CSV_FIELDS, extrasaction="ignore")
        writer.writeheader()
        writer.writerows(records)
    print(f"Exported {len(records)} records to {output_file}")

if __name__ == "__main__":
    filters = {
        "industry": "Manufacturing",
        "number_employees": {"min": 10, "max": 500},
        "date_filed": "1 year",
        "has_collateral": True
    }

    records = fetch_all_ucc_records(filters)
    export_to_csv(records, "ucc_debtor_results.csv")

Run the script:

Terminal

export LEADX_API_KEY="your_api_key_here"
python3 ucc_debtor_export.py

Available filter parameters

For quick reference, here are all the request parameters accepted by /ucc/debtor:

Parameter	Type	Description
`url`	string or string[]	Debtor company URL(s)
`company_id`	string or string[]	Debtor company ID(s)
`secured_party_company_id`	string or string[]	Secured-party company ID(s)
`debtor_type`	string or string[]	Debtor type(s): `Individual` or `Organization`. Omit to include both.
`phone`	string or string[]	Debtor phone number(s)
`name`	string or string[]	Debtor company name(s), fuzzy matched
`address`	string	Full or partial street address
`city`	string or string[]	Debtor city name(s)
`state`	string or string[]	Debtor state(s) (2-letter abbreviation)
`state_filing`	string or string[]	State where UCC was filed
`collateral`	string or string[]	Collateral description keyword(s)
`collateral_match_mode`	string	How multiple collateral terms are combined: `or` (default) matches any term, `and` requires all terms. Alias: `collateral_contains_operator`.
`assets`	string or string[]	Assets description keyword(s)
`has_collateral`	boolean	Filter for filings with collateral text
`has_assets`	boolean	Filter for filings with assets
`has_continuation`	boolean	Filter for filings with continuations
`has_amendment`	boolean	Filter for filings with amendments
`has_website`	boolean	Filter for filings with websites
`has_contacts`	boolean	Filter for filings with matched contacts
`industry`	string or string[]	Debtor industry/industries
`secured_party_industry`	string or string[]	Secured-party industry/industries
`naics_code`	string or string[]	Debtor NAICS code(s)
`naics_description`	string or string[]	Debtor NAICS description(s)
`eight_digit_sic_code`	string or string[]	Debtor 8-digit SIC code(s)
`four_digit_sic_code`	string or string[]	Debtor 4-digit SIC code(s)
`two_digit_sic_code`	string or string[]	Debtor 2-digit SIC code(s)
`filing_number`	string, int, or array	Filing number(s) — accepts a single string/int or a list
`date_filed`	string	Filing date — absolute (`YYYY-MM-DD`) or relative (`6 months`)
`date_expired`	string	Expiration date — supports `forwards`/`backwards` direction
`modified_date`	string	Last modified date — absolute or relative
`company_filing_count`	int, `[min,max]`, or `{min,max}`	Number of filings per company
`annual_revenue`	int, `[min,max]`, or `{min,max}`	Annual revenue range (USD)
`number_employees`	int, `[min,max]`, or `{min,max}`	Employee count range
`time_in_business`	int, `[min,max]`, or `{min,max}`	Years in business range
`one_filing_per_debtor`	boolean	Deprecated. Results are now always grouped by debtor. This parameter is ignored.
`exclude`	object	Exclude specific `url` or `phone` values
`sort_by`	string	Sort results by a supported field. Accepts `date_filed_unix`, `date_expired_unix`, `company_name`, or `secured_party`. Append `:asc` or `:desc` to set direction (for example, `date_filed_unix:desc`).
`sort_order`	string	Default sort direction (`asc` or `desc`) when `sort_by` does not include `:asc` or `:desc`.
`page`	int	Page number (default: `1`)
`per_page`	int	Records per page (default: `50`, max: `50`)

Next steps

You’ve seen how to query the UCC debtor API from basic lookups through advanced filtered searches. From here, you can:

Explore the UCC debtor field reference for a full breakdown of response fields
Use the UCC secured-party endpoint to search filings from the lender’s perspective
Combine UCC data with the companies endpoint to build complete credit risk profiles, as shown in the credit risk assessment guide

Getting Started

Endpoints

Field References

Guides

Prerequisites

Example 1: Look up a company by URL

Example 2: Look up by company name

Example 3: Filter by collateral and amendments

Example 4: Filter by industry and date range

Example 6: Combine multiple filters

Example 7: Filter by company size and filing count

Example 9: Export results to CSV with Python

Available filter parameters

Next steps

Getting Started

Endpoints

Field References

Guides

Documentation Index

​Prerequisites

​Example 1: Look up a company by URL

​Example 2: Look up by company name

​Example 3: Filter by collateral and amendments

​Example 4: Filter by industry and date range

​Example 5: Use pagination for large result sets

​Example 6: Combine multiple filters

​Example 7: Filter by company size and filing count

​Example 8: Automate pagination with Python

​Example 9: Export results to CSV with Python

​Available filter parameters

​Next steps

Prerequisites

Example 1: Look up a company by URL

Example 2: Look up by company name

Example 3: Filter by collateral and amendments

Example 4: Filter by industry and date range

Example 5: Use pagination for large result sets

Example 6: Combine multiple filters

Example 7: Filter by company size and filing count

Example 8: Automate pagination with Python

Example 9: Export results to CSV with Python

Available filter parameters

Next steps