> ## Documentation Index > Fetch the complete documentation index at: https://docs.leadx.com/llms.txt > Use this file to discover all available pages before exploring further. # Invoke the UCC debtor API > Step-by-step examples for querying UCC debtor records, from simple lookups to advanced filtered searches with pagination. 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](/getting-started/authentication) * 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. ```bash Terminal theme={null} 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"}' ``` ```python requests theme={null} 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: ```json 200 - Successful response theme={null} { "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`, `company_name`, `address`, `city`, or `zip_code` instead of `url`. To search within a geographic area, pass `near_zip_code` with `radius` (and an optional `radius_unit` of `mi` or `km`; defaults to `mi`). 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 `company_name` parameter supports fuzzy matching and accepts a single string or a list. ```bash Terminal theme={null} curl -X POST "https://api.leadx.com/v1/ucc/debtor" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"company_name": "Home Depot"}' ``` ```python requests theme={null} import requests url = "https://api.leadx.com/v1/ucc/debtor" headers = { "X-API-KEY": "YOUR_API_KEY", "Content-Type": "application/json", } payload = {"company_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: ```bash Terminal theme={null} curl -X POST "https://api.leadx.com/v1/ucc/debtor" \ -H "X-API-KEY: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"company_name": ["Home Depot", "Lowes"]}' ``` ```python requests theme={null} import requests url = "https://api.leadx.com/v1/ucc/debtor" headers = { "X-API-KEY": "YOUR_API_KEY", "Content-Type": "application/json", } payload = {"company_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: ```bash Terminal theme={null} 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 }' ``` ```python requests theme={null} 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: ```json 200 - Successful response (partial) theme={null} { "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`). ```bash Terminal theme={null} 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 }' ``` ```python requests theme={null} 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: ```bash Terminal theme={null} 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" }' ``` ```python requests theme={null} 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. ```bash Terminal theme={null} 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 }' ``` ```python requests theme={null} 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: ```json Pagination metadata theme={null} { "page_number": 1, "per_page": 50, "total_pages": 42, "total_records": 4165 } ``` Request subsequent pages by incrementing the `page` value: ```bash Terminal theme={null} 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 }' ``` ```python requests theme={null} 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](/getting-started/pagination) 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: ```bash Terminal theme={null} 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 }' ``` ```python requests theme={null} 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: ```bash Terminal theme={null} 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 }' ``` ```python requests theme={null} 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. ```bash Terminal theme={null} 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 }' ``` ```python requests theme={null} 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. ```python ucc_debtor_search.py theme={null} 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: ```bash Terminal theme={null} 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. ```python ucc_debtor_export.py theme={null} 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: ```bash Terminal theme={null} 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 or string\[] | Full or partial street address(es) | | `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](/field-references/ucc-debtor) for a full breakdown of response fields * Use the [UCC secured-party endpoint](/endpoints/ucc/fetch-secured-party-ucc-records) to search filings from the lender's perspective * Combine UCC data with the [companies endpoint](/endpoints/companies/fetch-company-details) to build complete credit risk profiles, as shown in the [credit risk assessment guide](/guides/perform-a-credit-risk-assessment)