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

## Middesk KYB

Use the **Middesk KYB** Workflow Builder block to search for possible Secretary of State (SOS) business-name matches and to run a full Know Your Business (KYB) verification. The block ID is `middesk_kyb`, and it is available for business entities in the **KYB** block group.

The block exposes two separate operations. They use the same Middesk integration, but they return different data and do not run in a fixed sequence.

## Available operations

| Operation | Service ID | Purpose | Processing |
| - | - | - | - |
| Middesk Business Search | `middesk_business_search` | Searches the application's formation state for business names similar to the submitted legal name. Use the results to assess likely SOS matches before or independently of full verification. | Synchronous. Lendflow stores the response as soon as Middesk returns it. |
| Middesk | `middesk` | Creates a Middesk Business and runs the configured verification orders. It can return identity, address, registration, TIN, people, watchlist, and other subscribed Middesk data. | Asynchronous. Lendflow waits for Middesk webhooks and retrieves the updated Business before marking the service successful. |

<Note>
  A Business Search result does not select a business or replace the full KYB
  report. It returns possible name matches, while the `middesk` operation runs
  full business verification. The workflow determines which operation runs and
  in what order.
</Note>

## Requirements

### Middesk Business Search

| Application field | Requirement | Notes |
| - | - | - |
| Business legal name | Required | Must be a non-empty string. |
| Formation state | Required | Use a supported two-letter state code, such as `CA`. This is the formation state, not the business address state. |

### Middesk

| Application field | Requirement | Notes |
| - | - | - |
| Business legal name | Required | Must be a non-empty string. |
| Business address line 1 | Required | Must be a non-empty street address. |
| Business address city | Required | Must be a non-empty city. |
| Business address state | Required | Use a valid state code. |
| Business address ZIP code | Required | Must pass ZIP-code validation. |
| Primary owner's telephone | Required | Must be a valid US telephone number. |
| Business owner first and last name | Required | Required for each submitted owner. |
| Business address line 2 | Optional | Additional address information. |
| Owner date of birth | Optional | Use `YYYY/MM/DD`; improves person and watchlist matching. |
| EIN | Optional | Must be a valid EIN; Lendflow normalizes the value. |
| Doing-business-as name | Optional | Used as an alternate business name, not the legal name. |
| Business website | Optional | Must be a valid URL. |
| Formation state | Optional | Use a valid two-letter state code. |

## Run through the API

Use bearer authentication for all Lendflow API requests. Your account must have the selected service enabled for the application.

1. Call `PUT /api/applications/{application_id}/enrich` through [Enrich Business Credit Application](/api-reference/workflow-management/enrich-business-credit-application) for the application.
2. Set `provider` to `middesk_business_search` or `middesk`. Queue the operations separately if you need both and need to control their order.
3. For `middesk`, `options.middeskProductOptions` is optional. Supported values in the current integration are `business_verification_verify`, `liens`, `ucc_liens`, and `tax_liens`.
4. A successful scheduling response is wrapped as `{"data":{"onqueue":true}}`. This confirms that Lendflow queued the work; it is not the Middesk result.
5. Call `GET /api/applications/{application_id}/commercial_data` through [Get Commercial Data](/api-reference/workflow-management/get-commercial-data) with `services[]=middesk` and `services[]=middesk_business_search` to retrieve status, dates, stored provider data, and stored requests.

The commercial-data response uses this Lendflow wrapper:

| Lendflow attribute | Type | Meaning | Possible values or format | When returned |
| - | - | - | - | - |
| `data.statuses` | object | Latest state or error for each requested service. | Keys include `middesk` and `middesk_business_search`. | When the related service is included. |
| `data.dates` | object | Latest service date keyed by exact service ID. | API timestamp or `null`. | When available. |
| `data.commercial_data` | object | Stored provider responses keyed by service ID. | Each value can be an object, array, or `null`. | When the related service is included. |
| `data.request_data` | object | Stored provider requests keyed by service ID. | Each value can be an object or `null`. | When the related service is included. |

## Run through Data Orchestration

Data Orchestration can run both Middesk operations.

1. In the Lendflow Dashboard, open **Builders > Data Orchestration**.
2. Create or edit a template and add the applicable Middesk operation from the **KYB** category.
3. Configure the conditions and connect each outcome to the next block.
4. Save and publish the template.
5. Call `POST /api/applications/{application_id}/data_orchestration/execute` through [Execute Data Orchestration](/api-reference/data-orchestration/execute-data-orchestration) with `template_id` and `application_id`. `stage_id` is optional, but when supplied it must identify a valid underwriting stage for the application.
6. Treat `{"data":{"executed":true}}` as confirmation that Lendflow scheduled the run, not as the Middesk result.
7. Follow the run through [Get Data Orchestration Log](/api-reference/data-orchestration/get-data-orchestration-log). Use [Get Commercial Data](/api-reference/workflow-management/get-commercial-data) with the applicable service in `services[]` when you need the provider payload.

For `middesk_business_search`, Data Orchestration can evaluate the result as soon as the synchronous search is stored. For `middesk`, Data Orchestration pauses while required Middesk orders are incomplete and resumes after Lendflow processes the webhook and retrieves the completed Business.

## What the service returns

| Result area | Operation | Provider response | How to interpret it |
| - | - | - | - |
| Candidate matches | `middesk_business_search` | A `data` array of possible SOS name records. | Compare `score`, `name`, state, and filing details. A candidate is not a verified Business. |
| Business lifecycle | `middesk` | Top-level Business `status` and timestamps. | This is Middesk's lifecycle, not the Lendflow service or Data Orchestration status. |
| Review findings | `middesk` | `review.tasks` with category, key, status, sub-label, and message. | Read each task as a provider finding. A failed task is a verification result and does not necessarily mean the API request failed. |
| TIN result | `middesk` | `tin` flags and error information. | Determine whether Middesk verified the submitted TIN and legal-name combination. |
| Formation and registrations | `middesk` | `formation` and `registrations`. | Use provider-normalized formation and SOS filing records. Empty arrays or `null` mean the provider returned no value in that response. |
| Addresses and people | `middesk` | `addresses` and `people`. | Compare submitted data with records and sources found by Middesk. |
| Screening and optional products | `middesk` | Objects or arrays such as `watchlist`, `bankruptcies`, `liens`, and `industry_classification`. | Availability depends on the account's Middesk products and the returned Business. |
| Order progress | `middesk` | `orders`. | Lendflow waits for all returned orders to be completed before Data Orchestration treats Middesk attributes as ready. |

## Representative response

The following sanitized example combines the current Lendflow fixture shapes inside the commercial-data wrapper.

```json theme={"system"}
{
  "data": {
    "statuses": {
      "middesk_business_search": "Success",
      "middesk": "Success"
    },
    "dates": {
      "middesk_business_search": "2026-09-10T15:00:01Z",
      "middesk": "2026-09-10T15:00:12Z"
    },
    "commercial_data": {
      "middesk_business_search": {
          "data": [
            {
              "name": "Example, Inc.",
              "state": "CA",
              "jurisdiction": "DOMESTIC",
              "score": 0.99
            }
          ]
      },
      "middesk": {
          "object": "business",
          "id": "51c4b91e-f324-467b-86b5-9e0155bcc251",
          "external_id": "f5f242f7-6250-487b-9beb-f6094f696755",
          "name": "EXAMPLE, INC.",
          "status": "in_review",
          "created_at": "2026-09-10T15:00:02.248Z",
          "updated_at": "2026-09-10T15:00:11.506Z",
          "review": {
            "completed_at": null,
            "tasks": [
              {
                "category": "name",
                "key": "name",
                "status": "success",
                "sub_label": "Verified",
                "message": "Match identified to the submitted Business Name"
              }
            ]
          },
          "tin": {
            "verified": true,
            "mismatch": false,
            "unknown": false,
            "issued": true,
            "error": null
          },
          "formation": {
            "formation_date": "2018-12-21",
            "entity_type": "CORPORATION"
          },
          "registrations": [],
          "addresses": [
            {
              "city": "San Francisco",
              "state": "CA",
              "postal_code": "94105",
              "address_line2": null,
              "submitted": true,
              "deliverable": true,
              "property_type": "COMMERCIAL"
            }
          ],
          "people": [],
          "watchlist": {
            "hit_count": 0
          },
          "orders": [
            {
              "product": "identity",
              "status": "completed",
              "completed_at": "2026-09-10T15:00:11.444Z"
            }
          ]
      }
    },
    "request_data": {
      "middesk_business_search": {},
      "middesk": {}
    }
  }
}
```

## Response attributes shown in the example

### Middesk Business Search provider data

| Attribute | Type | Meaning | Possible values or units | When returned |
| - | - | - | - | - |
| `data` | object\[] | Candidate SOS business-name records returned by the Middesk name-search operation. | Empty array when no candidate is returned. | On a successful search. |
| `data[].name` | string | Candidate registered business name. | Provider text. | For the fixture's returned candidate. |
| `data[].state` | string | State associated with the candidate filing. | Two-letter state code. | For the fixture's returned candidate. |
| `data[].jurisdiction` | string | Candidate filing's relationship to the state in the current Lendflow fixture. | `DOMESTIC` or `FOREIGN`. | When Middesk provides it. |
| `data[].score` | number | Relative name-match score used by Lendflow's **Name Search** attribute. | `0` through `1`; higher means a closer name match. No approval threshold is implied. | For the fixture's returned candidate. |

<Warning>
  Middesk's current public documentation does not describe the legacy
  `/v1/names/search` response contract used by this Lendflow operation. The
  candidate fields and `0`–`1` score above are validated against Lendflow's
  request implementation, models, tests, and fixture. Do not interpret this
  score as a sanctions-screening score or as a verified-business decision.
</Warning>

### Middesk Business provider data

| Attribute | Type | Meaning | Possible values or units | When returned |
| - | - | - | - | - |
| `object` | string | Middesk object type. | `business`. | On the Business object. |
| `id` | string | Middesk Business identifier. | UUID. | On the Business object. |
| `external_id` | string or null | Lendflow application ID sent to Middesk. | UUID in this integration; Middesk can otherwise return `null`. | On the Business object. |
| `name` | string | Business name on the Middesk Business. | Provider text. | On the Business object. |
| `status` | string | Middesk Business lifecycle state. | `open`, `pending`, `in_audit`, `in_review`, `approved`, or `rejected`. | On the Business object. |
| `created_at`, `updated_at` | string | Provider creation and last-update times. | ISO 8601 date-time with UTC offset, commonly `Z` and fractional seconds. | On the Business object. |
| `review.completed_at` | string or null | Time the review was completed. | ISO 8601 date-time, or `null` while no completion is recorded. | When a review object is present. |
| `review.tasks` | object\[] | Middesk findings for individual verification checks. | Empty until review findings are available. | When a review object is present. |
| `review.tasks[].category` | string | Group of the finding. | Example: `name`. | For each shown task. |
| `review.tasks[].key` | string | Machine-readable finding identifier. | Example: `name`. | For each shown task. |
| `review.tasks[].status` | string | Outcome severity for the finding. | Common values are `success`, `warning`, and `failure`. | For each shown task. |
| `review.tasks[].sub_label` | string | Short provider result label. | Depends on the task; example: `Verified`. | For each shown task. |
| `review.tasks[].message` | string | Human-readable provider explanation. | Provider text. | For each shown task. |
| `tin.verified` | boolean or null | Whether the submitted TIN matches the submitted legal name. | `true`, `false`, or `null` while unresolved. | When a TIN object is returned. |
| `tin.mismatch` | boolean or null | Whether Middesk found a different name associated with the TIN. | `true`, `false`, or `null` while unresolved. | When a TIN object is returned. |
| `tin.unknown` | boolean or null | Whether no associated name could be determined after verification failed. | `true`, `false`, or `null` while unresolved. | When a TIN object is returned. |
| `tin.issued` | boolean or null | Whether the TIN is issued. | `true`, `false`, or `null` when Middesk cannot determine it. | When a TIN object is returned. |
| `tin.error` | string or null | TIN verification error, such as temporary IRS unavailability. | Provider error string, or `null`. | When a TIN object is returned. |
| `formation.formation_date` | string or null | Date the business was formed. | `YYYY-MM-DD`, or `null` when unavailable. | When formation data is returned. |
| `formation.entity_type` | string or null | Provider-normalized legal entity type. | Example: `CORPORATION`; it can be `null`. | When formation data is returned. |
| `registrations` | object\[] | SOS registration records. | Empty array when none are returned. | On the fixture's Business object. |
| `addresses` | object\[] | Addresses submitted to or found by Middesk. | Empty array when none are returned. | On the Business object. |
| `addresses[].city`, `addresses[].state`, `addresses[].postal_code` | string or null | Provider-normalized address components. | State is usually a two-letter code; postal code can include ZIP+4. A component can be `null` when unavailable. | For the shown address. |
| `addresses[].address_line2` | string or null | Suite or secondary street information. | Provider text, or `null` when absent. | For the shown address. |
| `addresses[].submitted` | boolean | Whether the address was submitted for this Business. | `true` or `false`. | For the shown address. |
| `addresses[].deliverable` | boolean or null | Middesk's deliverability result. | `true`, `false`, or `null` when unresolved or unavailable. | For the shown address. |
| `addresses[].property_type` | string or null | Middesk's property classification. | Examples include `COMMERCIAL` and `RESIDENTIAL`; `null` when unavailable. | For the shown address. |
| `people` | object\[] | People submitted to or found by Middesk. | Empty array when none are returned. | On the Business object. |
| `watchlist.hit_count` | integer | Number of watchlist hits in the returned screening. | Zero or a positive integer. | When a watchlist object is returned. |
| `orders` | object\[] | Middesk products ordered for this Business. | Empty array when no order is present. | On the Business object. |
| `orders[].product` | string | Product associated with the order. | Example: `identity`. | For each shown order. |
| `orders[].status` | string | Provider order state. | Example: `completed`. | For each shown order. |
| `orders[].completed_at` | string or null | Time the order completed. | ISO 8601 date-time, or `null` before completion. | For each shown order. |

## Statuses and errors

Keep the following status layers separate:

| Layer | Status or error | Meaning |
| - | - | - |
| Lendflow API scheduling | HTTP success with `data.onqueue=true` | The direct enrichment request was accepted and queued. It does not mean provider processing finished. |
| Lendflow service lifecycle | `data.statuses.middesk_business_search` or `data.statuses.middesk`, plus the corresponding `data.dates` value | Tracks the latest service job. Business Search normally reaches success after the request returns. Middesk KYB remains unfinished until webhook processing marks it successful. |
| Middesk Business lifecycle | `open`, `pending`, `in_audit`, `in_review`, `approved`, or `rejected` | Tracks Middesk's Business verification and review lifecycle. `in_review` means Middesk has completed its investigation and the report is ready for review; it is not a Lendflow manual-review decision. |
| Middesk review task | `success`, `warning`, or `failure` | Describes one provider finding. A `failure` task can be a valid result such as an unverified name or missing registration. |
| Data Orchestration | Log `status`, `outcome`, and `internal_error` | Tracks the template run separately from service and provider status. A run can pause while asynchronous Middesk data is incomplete. |

Common failure cases include:

* Missing or invalid required application fields produce a validation error before Lendflow calls Middesk.
* An invalid U.S. phone number prevents the `middesk` request.
* Missing `formation_state` prevents `middesk_business_search`.
* An inactive or unavailable Middesk integration prevents the service from running.
* Middesk HTTP errors are stored with the provider response and status code, and Lendflow records the job as failed.
* A TIN request can return a provider-level error when the IRS is unavailable. Middesk can retry TIN verification and send a `tin.retried` webhook; this is different from a failed Lendflow API request.
* Running an unpublished, incompatible, unauthorized, or already-running Data Orchestration template can return validation, authorization, or conflict errors.

## FAQ

<AccordionGroup>
  <Accordion title="Does the Middesk KYB block always run both operations?">
    No. The block declares both `middesk_business_search` and `middesk` as
    related services, but API callers and Data Orchestration templates choose
    which service to run. A template controls whether both run and in what
    order.
  </Accordion>

  <Accordion title="Does Business Search verify the business?">
    No. It returns possible SOS name matches and relative scores. Run `middesk`
    for the full Business verification and review findings.
  </Accordion>

  <Accordion title="Why is Middesk commercial data null?">
    `data.commercial_data.middesk` remains `null` until Lendflow stores the
    provider response. Inspect `data.statuses.middesk` to distinguish an
    asynchronous run that is still processing from an error.
  </Accordion>

  <Accordion title="Does an in_review Middesk status mean the application failed?">
    No. `in_review` is a Middesk Business lifecycle status meaning the
    investigation is ready for your review. Review each task's status,
    sub-label, and message rather than treating the lifecycle status as a pass
    or fail result.
  </Accordion>

  <Accordion title="Can I use a Middesk API response without the Lendflow wrapper?">
    `data.commercial_data.middesk` is the stored provider response. The outer
    `data` object, including `statuses`, `dates`, and `request_data`, is
    Lendflow's wrapper and is not part of Middesk's schema.
  </Accordion>
</AccordionGroup>