> ## 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. # Start Liens Search > 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. ## OpenAPI ````yaml /api-reference/openapi.json post /lien_searches openapi: 3.1.0 info: title: baselayer-api-service version: 0.1.0 servers: - url: https://api.baselayer.com/ security: [] paths: /lien_searches: post: tags: - Lien Search summary: Start Liens Search description: >- 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. operationId: start_liens_search_lien_searches_post parameters: - name: Prefer in: header required: false schema: anyOf: - type: string - type: 'null' description: >- 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. examples: - respond-async - wait=30 - priority=low title: Prefer description: >- 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. requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/v1.BusinessLiensSearchRequest' - $ref: '#/components/schemas/v1.PersonLiensSearchRequest' - $ref: '#/components/schemas/v1.BusinessSearchLiensSearchRequest' title: Liens Request Object description: >- 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`. examples: - type: Business business_id: 832d7b08-001b-45cd-aa65-627bbf2bc2c0 search_states: - NY - CA - type: Person person_id: 2033e90a-cd3e-4978-a38e-1b9196d54e83 search_states: - DE - NJ - type: BusinessSearch business_search_id: 4076eb3a-0c3b-431e-868d-d33f9127da75 search_states: - NY - CA additional_search_entities: - name: John Doe type: Person search_states: - CA - name: Alt Name LLC type: Business search_states: - NY - CA responses: '201': description: Response content: application/json: schema: $ref: '#/components/schemas/v1.LiensSearchResponse' application/vnd.baselayer.v1+json: schema: $ref: '#/components/schemas/v1.LiensSearchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: v1.BusinessLiensSearchRequest: properties: type: type: string const: Business title: Type default: Business business_id: type: string format: uuid title: Business Id description: >- The ID of the business the liens search task should be run against. Mutually exclusive with person_id. search_states: anyOf: - items: $ref: '#/components/schemas/StateAbbreviation' type: array title: Override States for Liens Search description: >- 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. - type: 'null' title: Search for liens only in domestic state description: >- When set to `null`, the liens search will exclusively target the domestic state of the business for business searches. This is not supported for individual searches. A domestic state refers to the state within which the business has filed its articles of incorporation, and is recognized as its home state for legal and tax purposes. This is in contrast to any other states where the business might operate but is considered a foreign entity. The search, therefore, focuses on liens within this domestic jurisdiction, aligning with the legal recognition and operational base of the business. title: Search States additionalProperties: false type: object required: - business_id title: BusinessLiensSearchRequest (v1) description: Represents a request to initiate a liens search for a business. v1.PersonLiensSearchRequest: properties: type: type: string const: Person title: Type default: Person person_id: type: string format: uuid title: Person Id description: The ID of the person the liens search task should be run against. search_states: items: $ref: '#/components/schemas/StateAbbreviation' type: array title: Search States description: The states to search for liens in. additionalProperties: false type: object required: - person_id - search_states title: PersonLiensSearchRequest (v1) description: Represents a request to initiate a liens search for a person. v1.BusinessSearchLiensSearchRequest: properties: type: type: string const: BusinessSearch title: Type default: BusinessSearch business_search_id: type: string format: uuid title: Business Search Id description: >- The ID of the business search the liens search task should be run against. search_states: anyOf: - items: $ref: '#/components/schemas/StateAbbreviation' type: array title: Override States for Liens Search description: >- If provided, the search will exclusively target liens within these states, irrespective of the resolved business's registered states. - type: 'null' title: Search for liens only in domestic state description: >- When set to `null`, the liens search will exclusively target the domestic state of the resolved business for business searches. title: Search States additional_search_entities: anyOf: - items: $ref: '#/components/schemas/v1.AdditionalLiensSearchEntityRequest' type: array - type: 'null' title: Additional Search Entities description: >- A list of additional entities to be searched along with the business search in the liens search. examples: - - name: John Doe search_states: - CA type: Person - - name: Alt Name LLC search_states: - NY - CA type: Business additionalProperties: false type: object required: - business_search_id title: BusinessSearchLiensSearchRequest (v1) description: Represents a request to initiate a liens search for a business search. v1.LiensSearchResponse: description: >- 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. properties: id: description: The identifier of this liens search response. format: uuid title: Id type: string search_entities: description: A list of entities searched in the liens search. items: $ref: '#/components/schemas/v1.AdditionalLiensSearchEntityResponse' title: Search Entities type: array state: $ref: '#/components/schemas/v1.TaskState' description: The current state of the liens search request. error: anyOf: - type: string - type: 'null' default: null description: Any errors that occurred during the liens search request. examples: - 'TimeoutError: The Liens Search could not be completed.' title: Error filings: description: A list of lien filings associated with the search request. items: $ref: '#/components/schemas/v1.LienFilingResponse' title: Filings type: array last_updated_at: description: The date the lien search result was last updated. examples: - '2024-06-01' format: date title: Last Updated At type: string searched_states: anyOf: - description: >- 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. examples: - - FL - CA items: $ref: '#/components/schemas/v1.StateAbbreviation' title: States Specified for Liens Search type: array - description: >- Indicates that the liens search was limited to the domestic state of the business. A domestic state is defined as the state where the business filed its articles of incorporation and is considered its legal home state for tax purposes. This contrasts with any other states where the business might operate as a foreign entity. The search was thus focused on liens within this domestic jurisdiction, in line with the business's legal recognition and operational base. title: Liens Search Limited to Domestic State type: 'null' default: null title: Searched States business_id: anyOf: - type: string format: uuid - type: 'null' default: null description: The identifier of the business associated with these lien filings. examples: - bc145d0c-aea1-4572-844a-2d11ca1f85c0 title: Business Id person_id: anyOf: - type: string format: uuid - type: 'null' default: null description: The identifier of the person associated with these lien filings. examples: - 9cb64976-4cc4-4f52-8171-ce8744d52333 title: Person Id business_search_id: anyOf: - type: string format: uuid - type: 'null' default: null description: >- The identifier of the business search associated with these lien filings. examples: - 0b8d7416-e62c-420e-a593-7c86f26b1590 title: Business Search Id required: - id - search_entities - state - filings - last_updated_at title: LiensSearchResponse (v1) type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError StateAbbreviation: enum: - 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 title: StateAbbreviation type: string v1.AdditionalLiensSearchEntityRequest: properties: name: description: The name of the entity to search for. maxLength: 256 minLength: 1 title: Name type: string type: $ref: '#/components/schemas/BusinessOrPersonType' description: The type of the entity to search for. search_states: items: $ref: '#/components/schemas/StateAbbreviation' type: array minItems: 1 title: Search States description: The states to search for liens in. additionalProperties: false type: object required: - name - type - search_states title: AdditionalLiensSearchEntityRequest (v1) description: Represents a request to add an entity to a liens search. v1.AdditionalLiensSearchEntityResponse: properties: name: description: The name of the entity to search for. maxLength: 256 minLength: 1 title: Name type: string type: $ref: '#/components/schemas/v1.BusinessOrPersonType' description: The type of the entity to search for. search_states: description: The states to search for liens in. items: $ref: '#/components/schemas/v1.StateAbbreviation' minItems: 1 title: Search States type: array normalized_name: readOnly: true title: Normalized Name type: string required: - name - type - search_states - normalized_name title: AdditionalLiensSearchEntityResponse (v1) type: object v1.TaskState: enum: - PENDING - EXECUTING - COMPLETED - FAILED - CANCELLED title: TaskState type: string v1.LienFilingResponse: description: |- Contains detailed information about a lien filing, including the filing number, type, date, status, and associated business and search request. The model also links to any amendments and the involved parties. properties: id: description: The identifier of this lien filing record. format: uuid title: Id type: string state: $ref: '#/components/schemas/v1.StateAbbreviation' description: State abbreviation code where the lien is filed. examples: - CA filing_number: description: Sequential identifier assigned by the filing office. examples: - P98172 title: Filing Number type: string filing_type: description: Describes the nature of the filing. examples: - Lien for Loan Default title: Filing Type type: string filing_date: description: Official date when the lien was recorded. examples: - '2023-09-18' format: date title: Filing Date type: string lapse_date: description: The expiry date for the lien's claim on collateral. examples: - '2023-04-15' format: date title: Lapse Date type: string status: description: Reflects the current legal status of the lien. examples: - Under Appeal title: Status type: string number_of_pages: description: Reflects the volume of documentation for the lien filing. examples: - 14 title: Number Of Pages type: integer document_filename: anyOf: - description: >- 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. examples: - docket_47182.pdf title: The downloadable liens document filename. type: string - description: No downloadable documents are available for this lien filing. title: The downloadable document is not available. type: 'null' default: null title: Document Filename parties: default: [] description: >- 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. items: $ref: '#/components/schemas/v1.LienPartyResponse' title: Parties type: array amendments: default: [] description: >- 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. items: $ref: '#/components/schemas/v1.LienAmendmentResponse' title: Amendments type: array collateral_type: anyOf: - $ref: '#/components/schemas/v1.CollateralType' - type: 'null' default: null description: >- The classified type of collateral secured by this lien filing (e.g. blanket, all_receivables, real_property). Null when the collateral type has not been determined. collateral_statements: default: [] description: >- 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. items: $ref: '#/components/schemas/v1.LienCollateralStatementResponse' title: Collateral Statements type: array lien_amount: anyOf: - type: number - type: 'null' description: >- The total monetary amount owed for a tax lien filing. Null for non-tax filings. Serialized as a JSON number. examples: - 15432.5 title: Lien Amount last_updated_at: description: The date the lien filing record was last updated. format: date title: Last Updated At type: string match_level: anyOf: - $ref: '#/components/schemas/v1.MatchType' - type: 'null' default: null description: The match level of the lien filing to the business name search_entity_name: anyOf: - type: string - type: 'null' default: null description: The name of the entity that the lien filing matched to. title: Search Entity Name search_entity_type: anyOf: - $ref: '#/components/schemas/v1.BusinessOrPersonType' - type: 'null' default: null description: The type of the entity that the lien filing matched to. required: - id - state - filing_number - filing_type - filing_date - lapse_date - status - number_of_pages - last_updated_at title: LienFilingResponse (v1) type: object v1.StateAbbreviation: enum: - 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 title: StateAbbreviation type: string ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError BusinessOrPersonType: enum: - Business - Person title: BusinessOrPersonType type: string v1.BusinessOrPersonType: enum: - Business - Person title: BusinessOrPersonType type: string v1.LienPartyResponse: description: >- Represents an entity involved in a lien as either a debtor or a secured party. This model captures common attributes and relationships of these parties. properties: id: description: The identifier of this lien filing record. format: uuid title: Id type: string role: $ref: '#/components/schemas/v1.LienPartyRole' description: >- Categorizes the party as either a debtor owing the debt or a secured party holding the collateral interest. examples: - Debtor name: description: >- Legal name of the party; crucial for due diligence and legal proceedings related to the lien. examples: - Louis Schneider title: Name type: string address: anyOf: - $ref: '#/components/schemas/v1.AddressSummaryResponse' - type: 'null' description: >- Address of the party; provides the physical location for legal notices or contact purposes. mailing_address: anyOf: - type: string - type: 'null' default: null description: >- Street of the party's address as written on the filing itself, when known. It may accompany `address` rather than replace it: `address` is the verified address record behind the party when there is one, and these components are what the filing says — the only address a party with no verified record has. examples: - 1 Market Street title: Mailing Address city: anyOf: - type: string - type: 'null' default: null description: >- City of the party's address as recorded on the filing itself; see `mailing_address`. examples: - San Francisco title: City state: anyOf: - $ref: '#/components/schemas/v1.StateAbbreviation' - type: 'null' default: null description: >- State of the party's address as recorded on the filing itself; see `mailing_address`. examples: - CA postal_code: anyOf: - type: string - type: 'null' default: null description: >- Postal code of the party's address as recorded on the filing itself; see `mailing_address`. examples: - '94105' title: Postal Code type: description: >- 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. examples: - individual - organization title: Type type: string required: - id - role - name - address - type title: LienPartyResponse (v1) type: object v1.LienAmendmentResponse: description: |- Represents a change or update to a lien filing, such as a continuation, termination, or assignment that affects the lien's validity or terms. properties: filing_number: description: The document filing number. examples: - H76162 title: Filing Number type: string filing_type: description: The document filing type. examples: - Notarized Letter title: Filing Type type: string filing_date: description: The date of the lien filing. examples: - '2023-11-27' format: date title: Filing Date type: string number_of_pages: description: Number of image pages in the library for this filing number. examples: - 4 title: Number Of Pages type: integer required: - filing_number - filing_type - filing_date - number_of_pages title: LienAmendmentResponse (v1) type: object v1.CollateralType: description: Classifies the collateral grant on a lien filing. enum: - blanket - all_receivables - named_receivables - all_equipment - named_equipment - all_inventory - named_inventory - real_property - agricultural - other - not_applicable title: CollateralType type: string v1.LienCollateralStatementResponse: description: |- Represents the text descriptions of collateral pledged against a lien as recorded in a UCC filing. Each statement details the specific assets secured by the lien and is sorted by a 'sort_order' to maintain the intended sequence of claims. properties: text: description: >- A detailed description of the collateral that is subject to the lien. examples: - 2022 Blue Honda Civic title: Text type: string sort_order: description: >- An integer representing the display or priority order of the collateral statements. title: Sort Order type: integer required: - text - sort_order title: LienCollateralStatementResponse (v1) type: object v1.MatchType: enum: - NO_MATCH - SIMILAR - EXACT title: MatchType type: string v1.LienPartyRole: description: |- Enum class delineating the role of parties in a lien transaction as defined by the UCC. enum: - Debtor - Secured Party - Record Owner title: LienPartyRole type: string v1.AddressSummaryResponse: description: |- Response model for address summary data. This model defines the structure for address summary API responses. properties: id: description: Unique identifier for the address. format: uuid title: Id type: string street: description: Street name of the address. examples: - 913 Hendrix Gardens Suite 492 title: Street type: string city: description: City name of the address. examples: - Jasonfurt title: City type: string state: $ref: '#/components/schemas/v1.StateAbbreviation' description: State 2 letter abbreviation of the address. examples: - VA zip: description: Zip code of the address. examples: - '19773' title: Zip type: string latitude: description: Latitude of the address. examples: - 38.03012 title: Latitude type: number longitude: description: Longitude of the address. examples: - 78.47665 title: Longitude type: number rdi: anyOf: - $ref: '#/components/schemas/v1.AddressRDI' - type: 'null' default: null description: Residential Delivery Indicator of the address. examples: - Commercial deliverable: anyOf: - type: boolean - type: 'null' default: null description: Indicates whether the address is deliverable. examples: - false title: Deliverable cmra: anyOf: - type: boolean - type: 'null' default: null description: >- Indicates whether the address is a Commercial Mail Receiving Agency (CMRA). examples: - false title: Cmra url: anyOf: - format: uri maxLength: 2083 minLength: 1 type: string - type: 'null' default: null description: The URL to the address details. title: Url delivery_type: anyOf: - $ref: '#/components/schemas/v1.USPSDeliveryType' - type: 'null' default: null description: The USPS delivery type. examples: - STREET - FIRM required: - id - street - city - state - zip - latitude - longitude title: AddressSummaryResponse (v1) type: object v1.AddressRDI: enum: - Residential - Commercial title: AddressRDI type: string v1.USPSDeliveryType: description: |- Enum representing the different types of USPS delivery points. Used to classify addresses based on how mail is delivered to them. enum: - FIRM - GENERAL_DELIVERY - HIGH_RISE - POST_OFFICE - RURAL_ROUTE - STREET title: USPSDeliveryType type: string securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key ````