---
title: "Start Liens Search"
method: POST
path: "/lien_searches"
tags: ["Lien Search"]
---

# Start Liens Search

`POST /lien_searches`

This endpoint starts a liens search for a given person or business.
Exactly one of `business_id` or `person_id` must be provided. If `person_id`
is provided, `search_states` must be provided.

By default, this endpoint executes synchronously and returns the completed
result. Send ``Prefer: respond-async`` to opt into asynchronous execution,
which returns ``202 Accepted`` immediately and delivers results via
webhooks or polling.

## Headers

- `Prefer` string, nullable — Request execution preference (RFC 7240). Use ``respond-async`` for asynchronous execution, ``wait=N`` to specify a synchronous timeout hint in seconds, or ``priority=low`` to route the task to the low-priority queue.

## Request body

- union — Request body for starting a liens search, discriminated by `type`. Use a business record with `business_id` (and optional `search_states`), or a person record with `person_id` and required `search_states`.
  - V1BusinessLiensSearchRequest — Represents a request to initiate a liens search for a business.
    - `type` 'Business'
    - `business_id` string, uuid, required — The ID of the business the liens search task should be run against. Mutually exclusive with person_id.
    - `search_states` StateAbbreviation[], nullable — This is required for individual searches. For business searches, specifies an override list of states for the liens search. If provided, the search will exclusively target liens within these states, irrespective of the business's registered states.
  - V1PersonLiensSearchRequest — Represents a request to initiate a liens search for a person.
    - `type` 'Person'
    - `person_id` string, uuid, required — The ID of the person the liens search task should be run against.
    - `search_states` StateAbbreviation[], required — The states to search for liens in.
  - V1BusinessSearchLiensSearchRequest — Represents a request to initiate a liens search for a business search.
    - `type` 'BusinessSearch'
    - `business_search_id` string, uuid, required — The ID of the business search the liens search task should be run against.
    - `search_states` StateAbbreviation[], nullable — If provided, the search will exclusively target liens within these states, irrespective of the resolved business's registered states.
    - `additional_search_entities` V1AdditionalLiensSearchEntityRequest[], nullable — A list of additional entities to be searched along with the business search in the liens search.
      - `name` string, required — The name of the entity to search for.
      - `type` 'Business' | 'Person', required
      - `search_states` StateAbbreviation[], required — The states to search for liens in.

## Response `201`

Response

- V1LiensSearchResponse — Represents the response from a liens search request. This includes the unique identifier of the request, the current state of the request, and a list of lien filings associated with the request.
  - `id` string, uuid, required — The identifier of this liens search response.
  - `search_entities` V1AdditionalLiensSearchEntityResponse[], required — A list of entities searched in the liens search.
    - `name` string, required — The name of the entity to search for.
    - `type` 'Business' | 'Person', required
    - `search_states` V1StateAbbreviation[], required — The states to search for liens in.
    - `normalized_name` string, required
  - `state` 'PENDING' | 'EXECUTING' | 'COMPLETED' | 'FAILED' | 'CANCELLED', required
  - `error` string, nullable — Any errors that occurred during the liens search request.
  - `filings` V1LienFilingResponse[], required — A list of lien filings associated with the search request.
    - `id` string, uuid, required — The identifier of this lien filing record.
    - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'DC' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'PR' | 'VI' | 'AE' | 'AA' | 'AP' | 'GU' | 'AS', required
    - `filing_number` string, required — Sequential identifier assigned by the filing office.
    - `filing_type` string, required — Describes the nature of the filing.
    - `filing_date` string, date, required — Official date when the lien was recorded.
    - `lapse_date` string, date, required — The expiry date for the lien's claim on collateral.
    - `status` string, required — Reflects the current legal status of the lien.
    - `number_of_pages` integer, required — Reflects the volume of documentation for the lien filing.
    - `document_filename` string, nullable — When present, it indicates that a document is available for download; Use get_lien_filing_documents or get_lien_filing_documents_for_business_id to download the documents.
    - `parties` V1LienPartyResponse[] — A list of parties associated with this lien filing, encompassing both debtors and secured parties. This relationship is critical for identifying all entities with a vested interest in the lien's terms and outcome.
      - `id` string, uuid, required — The identifier of this lien filing record.
      - `role` 'Debtor' | 'Secured Party' | 'Record Owner', required — Enum class delineating the role of parties in a lien transaction as defined by the UCC.
      - `name` string, required — Legal name of the party; crucial for due diligence and legal proceedings related to the lien.
      - `address` V1AddressSummaryResponse, required — Response model for address summary data. This model defines the structure for address summary API responses.
        - `id` string, uuid, required — Unique identifier for the address.
        - `street` string, required — Street name of the address.
        - `city` string, required — City name of the address.
        - `state` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'DC' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'PR' | 'VI' | 'AE' | 'AA' | 'AP' | 'GU' | 'AS', required
        - `zip` string, required — Zip code of the address.
        - `latitude` number, required — Latitude of the address.
        - `longitude` number, required — Longitude of the address.
        - `rdi` 'Residential' | 'Commercial'
        - `deliverable` boolean, nullable — Indicates whether the address is deliverable.
        - `cmra` boolean, nullable — Indicates whether the address is a Commercial Mail Receiving Agency (CMRA).
        - `url` string, uri, nullable — The URL to the address details.
        - `delivery_type` 'FIRM' | 'GENERAL_DELIVERY' | 'HIGH_RISE' | 'POST_OFFICE' | 'RURAL_ROUTE' | 'STREET' — Enum representing the different types of USPS delivery points. Used to classify addresses based on how mail is delivered to them.
      - `type` string, required — The type of lien party, indicating whether the party is an individual or an organization. A computed property that returns the role of the lien party. Note: This `type` property is planned to be deprecated in favor of the `role` field in future versions.
    - `amendments` V1LienAmendmentResponse[] — A chronological list of amendments to this lien filing, detailing any continuations, terminations, or modifications. This historical record is fundamental for tracking the evolution and current standing of the lien.
      - `filing_number` string, required — The document filing number.
      - `filing_type` string, required — The document filing type.
      - `filing_date` string, date, required — The date of the lien filing.
      - `number_of_pages` integer, required — Number of image pages in the library for this filing number.
    - `collateral_statements` V1LienCollateralStatementResponse[] — A sequence of collateral statements associated with this lien filing, enumerating the specific assets secured by the lien. The order of these statements can denote the priority of claims against the assets.
      - `text` string, required — A detailed description of the collateral that is subject to the lien.
      - `sort_order` integer, required — An integer representing the display or priority order of the collateral statements.
    - `last_updated_at` string, date, required — The date the lien filing record was last updated.
    - `match_level` 'NO_MATCH' | 'SIMILAR' | 'EXACT'
    - `search_entity_name` string, nullable — The name of the entity that the lien filing matched to.
    - `search_entity_type` 'Business' | 'Person'
  - `last_updated_at` string, date, required — The date the lien search result was last updated.
  - `searched_states` V1StateAbbreviation[], nullable — Indicates the list of states specified in the liens search request. When states are provided, the search was limited to liens within these specified states, regardless of the business's registered states.
  - `business_id` string, uuid, nullable — The identifier of the business associated with these lien filings.
  - `person_id` string, uuid, nullable — The identifier of the person associated with these lien filings.
  - `business_search_id` string, uuid, nullable — The identifier of the business search associated with these lien filings.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/baselayer/apis/baselayer-api-service.md) · [All operations](https://skmtc.net/baselayer/apis/baselayer-api-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/baselayer/baselayer-api-service/versions/0cc89938bc26/schema)