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

# Start Liens Adhoc Search

`POST /lien_searches/adhoc`

Start an ad-hoc liens search using a name and explicit search states.

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

- V1AdhocLiensSearchRequest — Body for ``POST /lien_searches/adhoc``
  - `name` string, required — The name to search liens for.
  - `search_states` StateAbbreviation[], required — The states to search for liens in.

## Response `201`

Response

- V1AdhocLiensSearchResponse — Represents the response from an adhoc 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.
  - `name` string, required — The name used for the ad-hoc liens search.
  - `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[], required — Indicates the list of states specified in the liens search request.

## 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)