> ## Documentation Index
> Fetch the complete documentation index at: https://docs.baselayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lien Search: Basics

> How Baselayer's Lien Search product works: coverage, response structure, and how to get started.

This guide covers how Baselayer's Lien Search product works: what it searches, how results are returned, and what the response contains.

For background on lien types, UCC filings, and key terminology, see [Liens, Judgments, and Public Records](/docs/liens-judgments-and-public-records) before reading this guide.

For step-by-step API implementation, see [Lien Search: API Quickstart](/docs/lien-search-api-quickstart).

***

## 1. What Baselayer Searches

A Baselayer lien search retrieves public lien filings from Secretary of State (SoS) registries across the United States.

**Baselayer returns:**

* UCC filings (UCC-1, UCC-3, UCC-5)
* Federal tax liens (IRS)
* State tax liens
* County and municipal tax liens
* Judgment liens (where available)
* Associated lien documents (PDFs), where available by state

**Coverage and refresh rates** vary by state. Contact your Baselayer representative for the current coverage map and data freshness details for states relevant to your use case.

***

## 2. Execution Mode

Lien searches support both synchronous and asynchronous execution, controlled via the `Prefer` header or your API key's default mode. For full details, see [Synchronous & Asynchronous Request Execution](/docs/synchronous-asynchronous-request-execution).

Lien-specific webhook events emitted during async execution:

| Event | When it fires |
| :- | :- |
| `LiensSearch.submitted` | Search has been accepted and is in progress |
| `LiensSearch.completed` | Results are ready for retrieval |
| `LiensSearch.failed` | Search has failed to execute |

> **Note:** Ad-hoc (name-based) lien searches never emit webhooks. Use the synchronous response, or poll `GET /lien_searches/{lien_search_request_id}` when executing asynchronously.

***

## 3. State Coverage Model

Lien filings follow the **debtor's state of formation** under UCC rules. This means the domestic state - the state where the business is incorporated or formed - is where UCC liens are **perfected** and effective.

**By default, Baselayer searches only the domestic state.** Omitting `search_states` from the request is the recommended approach for most customers.

Every state searched incurs a direct data cost. Searching all foreign-registered states without reason adds unnecessary spend without meaningfully improving lien coverage.

**When to add additional states:**

* The business is incorporated in one state but operates primarily in another — in this case, search both the incorporation state and the state of the business's submitted address.
* Collateral is physically located in a specific non-domestic state (common in equipment financing or inventory-backed lending).
* The product or customer base requires a more thorough analysis including lien searches in all registered states.
* The product involves non-standard asset classes tied to a specific geography.

> **Note:** Tax liens may occasionally appear in foreign-registered states when the business has tax obligations there - for example, sales tax, payroll tax, or franchise tax. These are typically smaller and lower risk than domestic tax liens, unless the business's primary operations are outside its domestic state.

**Why searching all 50 states is never the right choice**

A business name is not a unique identifier at the national level. The same name can belong to entirely unrelated, independently incorporated companies across different states.

Searching all 50 states expands the pool of unrelated businesses whose filings will appear in your results, creating false positives that require manual review to dismiss. The domestic state (and, when warranted, additional foreign states with a specific rationale) is always the right scope. Broader is not better here.

***

## 4. Three Ways to Initiate a Lien Search

Baselayer supports three request types for `POST /lien_searches`, depending on what identifiers you have available:

**Option 1: Using a `business_id`**

Use a `business_id` from a previous Baselayer Business Search. The search targets the business's domestic state unless `search_states` is provided.

**Option 2: Using a `business_search_id` with optional `additional_search_entities`**

Use the `id` returned directly from a Business Search response. This variant also supports `additional_search_entities`, which allows you to search for linked individuals (officers, guarantors, beneficial owners) or alternate business names in the same API call.

This is the most powerful request type and the recommended approach when you need lien coverage beyond the primary business entity.

**Option 3: Using a `person_id`**

Use a `person_id` from a previous Baselayer person record. When using this option, `search_states` is required. This is covered in detail in [Lien Search for Individuals](/docs/lien-search-for-individuals).

***

## 5. Response Structure

The primary content of the API response is the `filings` array: one object per lien filing found.

**Top-level response fields:**

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Unique identifier of the lien search request |
| `state` | string | Current state of the request (`PENDING`, `EXECUTING`, `COMPLETED`, `FAILED`, `CANCELLED`) |
| `search_entities` | array | The entities searched - see Section 5.1 |
| `filings` | array | List of lien filing objects - see Section 5.2 |
| `searched_states` | array | States included in the search |
| `business_id` | UUID \| null | Business associated with the search, if applicable |
| `person_id` | UUID \| null | Person associated with the search, if applicable |
| `business_search_id` | UUID \| null | Business search ID used to initiate the request, if applicable |
| `last_updated_at` | date | Date the result was last refreshed |
| `error` | string \| null | Error message if the search failed |

***

### 5.1 Search Entities

The `search_entities` array lists every entity included in the search, the primary business and any additional entities submitted via `additional_search_entities`. Each entry includes:

| Field | Description |
| - | - |
| `name` | Name of the entity as submitted |
| `normalized_name` | Name as normalized by Baselayer for matching against registry records |
| `type` | `"Business"` or `"Person"` |
| `search_states` | States searched for this entity |

The `normalized_name` is the name Baselayer actually used when querying each state's registry. Reviewing it helps understand which name variants were matched, particularly for businesses with abbreviations, punctuation, or common alternate forms.

***

### 5.2 Filing Object Fields

Each object in the `filings` array represents a single lien filing.

| Field | Description |
| - | - |
| `id` | Unique identifier of the filing; used for document retrieval |
| `state` | US state where the lien was filed |
| `filing_number` | Unique identifier in the state's SoS registry |
| `filing_type` | Normalized filing classification - see Section 5.3 |
| `filing_date` | Date the security interest was officially recorded |
| `lapse_date` | Date the filing expires if not continued (typically 5 years from `filing_date`) |
| `status` | Current status of the filing (`active`, `terminated`, `lapsed`). Baselayer derives this from the filing and its amendments, so it already reflects terminations and continuations — treat it as the authoritative open/closed signal |
| `number_of_pages` | Number of pages in the associated document, if available. Descriptive only — it is not a promise that a document can be retrieved; check `document_filename` for that |
| `document_filename` | Non-null if a lien document PDF is available for download |
| `parties` | List of parties associated with the filing - see Section 5.4 |
| `amendments` | Chronological list of amendment filings against this record - see Section 5.5 |
| `collateral_statements` | Textual descriptions of the assets covered by the lien - see Section 5.6 |
| `match_level` | How closely this filing matched the searched entity name - see Section 5.7 |
| `search_entity_name` | Name of the entity this filing was matched against |
| `search_entity_type` | Type of the matched entity: `"Business"` or `"Person"` |
| `last_updated_at` | Date this filing record was last refreshed |

***

### 5.3 Filing Type (`filing_type`)

The `filing_type` field is Baselayer's normalized classification of each lien filing. It is consistent across all states and is the field to use for programmatic classification logic.

**Consensual liens** (created by agreement between lender and borrower):

| Value | Description |
| - | - |
| `consensual.ucc` | Standard UCC financing statement |
| `consensual.ucc_public_finance` | UCC filing related to public sector financing |
| `consensual.ucc_manufactured_home` | UCC filing for manufactured home collateral |
| `consensual.ucc_transmitting_utility` | UCC filing for transmitting utility collateral |
| `consensual.other` | Other consensual lien type |

**Statutory liens** (created by operation of law):

| Value | Description |
| - | - |
| `statutory.hospital_medical` | Medical or hospital lien |
| `statutory.agricultural` | Agricultural lien |
| `statutory.other` | Other statutory lien |

**Judicial liens** (arising from court proceedings):

| Value | Description |
| - | - |
| `judicial.judgment` | Court judgment lien |
| `judicial.attachment` | Pre-judgment attachment lien |
| `judicial.execution` | Lien arising from execution of a judgment |
| `judicial.other` | Other judicial lien |

**Tax liens** (filed by government authorities):

| Value | Description |
| - | - |
| `tax.federal_irs` | IRS federal tax lien |
| `tax.federal_estate` | Federal estate tax lien |
| `tax.federal_other` | Other federal tax lien |
| `tax.state_unemployment` | State unemployment tax lien |
| `tax.state_income_sales_franchise` | State income, sales, or franchise tax lien |
| `tax.state_other` | Other state tax lien |
| `tax.local_property_tax` | Local property tax lien |
| `tax.local_other` | Other local/municipal tax lien |
| `tax.other` | Other tax lien |

**Detecting tax liens:** Any filing where `filing_type` starts with `tax.` is a government-originated tax lien. No keyword matching on raw registry strings is required.

**Detecting judicial liens:** Any filing where `filing_type` starts with `judicial.` results from a court proceeding.

***

### 5.4 Parties

The `parties` array lists all parties associated with a filing. Each party includes:

| Field | Description |
| - | - |
| `id` | Unique identifier of the party record |
| `role` | `"Debtor"`, `"Secured Party"`, or `"Record Owner"` |
| `name` | Name of the party |
| `address` | Full address of the party, including geocoordinates where available |

***

### 5.5 Amendments

The `amendments` array contains a chronological record of all follow-on filings made against the original lien. Each amendment includes:

| Field | Description |
| - | - |
| `filing_number` | The amendment's unique identifier in the state registry |
| `filing_type` | Type of amendment — see enum table below |
| `filing_date` | Date the amendment was filed |
| `number_of_pages` | Number of pages in the amendment document |

**Amendment `filing_type` values:**

Raw amendment codes from each state registry are normalized into this fourteen-value set at ingestion. Codes that cannot be mapped become `unspecified`.

| Value | Description |
| - | - |
| `termination` | Lien formally ended - debt satisfied or security interest released by the secured party |
| `continuation` | Lien perfection extended beyond its original lapse date - secured party is actively maintaining the filing |
| `assignment` | Security interest transferred to a new secured party - common when loans are sold or refinanced |
| `debtor_amendment.add` | A debtor was added to the filing |
| `debtor_amendment.remove` | A debtor was removed from the filing |
| `debtor_amendment.update` | Debtor information was updated (name, address, or entity type) |
| `secured_party_amendment.add` | A secured party was added to the filing |
| `secured_party_amendment.remove` | A secured party was removed from the filing |
| `secured_party_amendment.update` | Secured party information was updated |
| `collateral_amendment.add` | Additional collateral was added to the filing |
| `collateral_amendment.remove` | Collateral was removed from the filing - reduces the scope of the lien |
| `collateral_amendment.update` | Collateral description was modified |
| `informational` | Informational statement only - no change to lien status or terms |
| `unspecified` | Amendment type could not be mapped from the state registry's raw code |

Reading the amendments array gives you the full lifecycle of a lien, but you do not need to parse it to determine whether the lien is open or closed. The top-level `status` field already incorporates amendment effects under the UCC §9-515 rollup rules: a `termination` amendment produces `status: "terminated"`, a `continuation` filed within the statutory window keeps the filing `active`, and otherwise the lapse date decides `active` vs `lapsed`. **Treat `status` as the authoritative open/closed signal and `amendments[]` as supporting evidence.** A `continuation` confirms the secured party is actively maintaining the filing. `collateral_amendment.remove` or `collateral_amendment.update` entries may indicate restructuring or partial release of pledged assets and are worth reviewing in larger-ticket underwriting.

***

### 5.6 Collateral Statements

The `collateral_statements` array contains textual descriptions of the assets covered by the lien, exactly as recorded in the state registry. Each entry includes:

| Field | Description |
| - | - |
| `text` | Collateral description as filed (e.g. `"All assets"`, `"2022 Blue Honda Civic"`, `"Accounts receivable"`) |
| `sort_order` | Display order when multiple collateral statements are present |

Collateral statements are particularly useful for determining the scope of a lien. A broad "all assets" description indicates a blanket lien; specific descriptions (equipment, vehicles, inventory) indicate a narrower security interest limited to particular asset categories.

***

### 5.7 Match Level

The `match_level` field indicates how closely the filing's debtor name matched the searched entity name. Possible values are `EXACT`, `SIMILAR`, and `NO_MATCH`. Baselayer applies a strict matching process, so all returned filings will carry an `EXACT` or `SIMILAR` match level.

***

### 5.8 Document Availability

PDF documents are available for many filings at no additional cost, subject to state availability and filing date.

To check availability: inspect `document_filename` on any filing object. A non-null value indicates a document is available.

To retrieve the document:

```
GET /lien_searches/{liens_search_request_id}/filings/{filing_id}
```

This returns a **307 redirect** to a signed URL for a consolidated PDF of all documents associated with that filing — configure your HTTP client to follow redirects. Not all states provide documents digitally; availability of historical filings (particularly pre-2010) varies.

> **Note:** `number_of_pages` is descriptive metadata only. A filing can report a page count without having a retrievable document — `document_filename` being non-null is the only reliable signal that a download is available.

***

## 6. Where to Go Next

* **[Lien Search: API Quickstart](/docs/lien-search-api-quickstart)** — Step-by-step implementation with full code examples
* **[Lien Search: Best Practices](/docs/lien-searching-best-practices)** — State scope strategy, risk classification, and decisioning frameworks
* **[Lien Search for Individuals](/docs/lien-search-for-individuals)** — Searching liens for sole proprietors, officers, guarantors, and beneficial owners
* **[Liens, Judgments, and Public Records](/docs/liens-judgments-and-public-records)** — Background on lien types, UCC filings, and key terminology


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.