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

# Middesk Liens

## Middesk Liens

The **Middesk Liens** Workflow Builder block retrieves lien records from the shared `middesk` service. Depending on the Middesk account type, the block can request a combined liens product or separate UCC-lien and tax-lien products.

## What the service returns

| Result area | Meaning |
| - | - |
| Lien records | State, federal, and UCC records associated with the business. |
| Parties and filing | Debtors, secured parties, filing identifiers and dates, status, amounts, collateral, and documents when returned. |
| Lifecycle and request | Lendflow stores the latest `middesk` status, date, and sanitized request separately. |

An empty `liens` array is a successful no-record result only when the lifecycle status is successful.

## Requirements

| Application field | Requirement | Notes |
| - | - | - |
| Business legal name | Required | Use the legal name stored on the application. |
| Primary business address line 1, city, state, and ZIP code | Required | Provide all listed address fields. |
| Primary owner's telephone | Required | Use a valid United States telephone number. |
| Every owner's full name | Required | Provide the full name for each owner on the application. |
| Owner date of birth | Optional | Use `YYYY/MM/DD` when provided. |
| EIN | Optional | The value must pass validation when provided. |
| Website, DBA, and formation state | Optional | These fields provide additional business information when available. |
| Lien product selection | Required | Select one option available to the client: combined liens, UCC liens, or tax liens. |

## Select a lien product

Retrieve the options available to the client rather than assuming an account type. Lendflow exposes them as `liens_options`.

| Returned option | Meaning |
| - | - |
| `liens` | Combined legacy Middesk liens order. |
| `ucc_liens` | UCC liens order for a newer Middesk account. |
| `tax_liens` | Tax liens order for a newer Middesk account. |

Only values returned for the client should be submitted. A newer account receives `ucc_liens` and `tax_liens`; an older account receives `liens`.

## Run the service

Call [Enrich Business Credit Application](/api-reference/workflow-management/enrich-business-credit-application) at `PUT /api/applications/{application_id}/enrich`:

```json theme={"system"}
{
  "provider": "middesk",
  "options": {
    "middeskProductOptions": ["ucc_liens"]
  }
}
```

Submit one available option per block run. The API returns `{"data":{"onqueue":true}}` when the job is queued.

For newer Middesk accounts, Lendflow includes the selected order and the required `business_verification_verify` package when creating the business. For older accounts, Lendflow creates the selected order after a Middesk business-update webhook.

## Retrieve the result

Poll [Get Commercial Data](/api-reference/workflow-management/get-commercial-data) with `services[]=middesk`.

| Data | Response path |
| - | - |
| Stored Middesk response | `commercial_data.middesk` |
| Lien records | `commercial_data.middesk.liens` |
| Latest status | `statuses.middesk` |
| Stored request | `request_data.middesk` |
| Latest date | `dates.middesk` |

Call `GET /api/applications/{application_id}/commercial_data?services[]=middesk`. Use `statuses.middesk` and `dates.middesk` to track the latest run, `commercial_data.middesk` for the provider response, and `request_data.middesk` for the stored request.

## Asynchronous behavior

Middesk is always queued and completes through webhook updates. Lendflow marks the run `Success` only after the business status is `in_review`, `approved`, or `declined` and every returned order is `completed`.

Rerun the block to request another product or refresh data. Because all Middesk legal blocks share `middesk`, use the latest run's context and response when comparing results.

## Example response

```json theme={"system"}
{
  "liens": [
    {
      "id": "lien_example_001",
      "object": "lien",
      "type": "ucc",
      "state": "CO",
      "status": "open",
      "status_category": "open",
      "file_number": "123456",
      "filing_date": "2023-10-21",
      "lapse_date": "2028-10-21",
      "liability_cents": null,
      "collateral": "All assets",
      "negative_pledge": false,
      "debtors": [{ "name": "Example Company LLC", "addresses": [] }],
      "secured_parties": [{ "name": "Example Secured Party", "addresses": [] }],
      "documents": []
    }
  ]
}
```

## Response fields

| Field | Type | Meaning | Values or units | When returned |
| - | - | - | - | - |
| `liens` | array | Lien records associated with the business. | Empty or record objects. | When lien data is included. |
| `liens[].id` | string | Middesk lien identifier. | Provider identifier. | For each record. |
| `liens[].object` | string | Middesk object type. | `lien`. | For each record. |
| `liens[].type` | string | Lien category. | Observed values include `state`, `federal`, and `ucc`. | For each record. |
| `liens[].state` | string or null | Filing state. | Two-letter state code when known. | When available. |
| `liens[].status` | string or null | Provider filing status. | Provider text such as `open`. | When available. |
| `liens[].status_category` | string or null | Middesk's normalized status grouping. | Provider category such as `open`. | When available. |
| `liens[].file_number` | string or null | Filing-office record number. | Jurisdiction-defined text. | When available. |
| `liens[].filing_date` | string or null | Original filing date. | `YYYY-MM-DD`. | When available. |
| `liens[].lapse_date` | string or null | Scheduled lapse date. | `YYYY-MM-DD`. | When available. |
| `liens[].liability_cents` | integer or null | Reported liability in cents. | Currency minor units; divide by 100 for dollars. | Common for tax liens. |
| `liens[].collateral` | string or null | Collateral description. | Provider text. | Common for UCC liens. |
| `liens[].negative_pledge` | boolean or null | Whether the filing contains a negative pledge indicator. | `true` or `false`. | When available. |
| `liens[].debtors` | array | Debtors named in the filing. | Party objects. | For each record. |
| `liens[].debtors[].name` | string | Debtor name. | Provider text. | For each debtor. |
| `liens[].debtors[].addresses` | array | Addresses associated with the debtor. | Address objects; can be empty. | When available. |
| `liens[].secured_parties` | array | Secured parties named in the filing. | Party objects. | When available. |
| `liens[].secured_parties[].name` | string | Secured-party name. | Provider text. | For each secured party. |
| `liens[].secured_parties[].addresses` | array | Addresses associated with the secured party. | Address objects; can be empty. | When available. |
| `liens[].documents` | array | Filing documents returned by Middesk. | Empty or document objects. | When available. |

The provider can return additional fields such as source, update date, packet or confirmation number, collateral type, termination data, and principal amount. They are intentionally omitted because this example does not claim a fixed schema beyond fields shown.

## Data Orchestration

Middesk Liens is available under **Liens → Middesk**. Conditions use the completed `middesk` result and can distinguish federal-tax, state-tax, and UCC lien collections. The service must run before dependent conditions.

## Errors

| Result | Meaning | Action |
| - | - | - |
| HTTP `401` or `403` | Authentication or application permission failed. | Use a token with view and enrichment access. |
| HTTP `422` | Provider access, body, or product option is invalid. | Confirm `middesk` is enabled and use an option returned in `liens_options`. |
| Phone validation error | The primary-owner telephone is not valid for the US request. | Correct the application and rerun. |
| `failed_at` or error status | Validation, provider, order creation, or webhook processing failed. | Inspect the lifecycle error and `statuses.middesk`. |
| Run remains in progress | The business or one of its orders is incomplete. | Continue polling. |

## FAQ

<AccordionGroup>
  <Accordion title="Why do the available option names differ by client?">
    Middesk account generations use different order packages. Use the client's returned `liens_options`; do not hard-code `liens`, `ucc_liens`, or `tax_liens`.
  </Accordion>

  <Accordion title="Can I request UCC and tax liens in one enrichment call?">
    The API context accepts an array, but the current block UI selects one option for each run. Submit one available product per block run to match that behavior.
  </Accordion>

  <Accordion title="Why does this block share a status with Middesk Bankruptcies?">
    Both blocks run `middesk` and read different sections of the same stored business response.
  </Accordion>

  <Accordion title="Does onqueue true mean the lien order completed?">
    No. Continue polling until the run finishes or fails.
  </Accordion>
</AccordionGroup>