> ## 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 Business Match

## Middesk Business Match

Middesk Business Match searches Secretary of State business-name records using the application's legal name and formation state. It returns possible matches and relative name-match scores; it does not create or verify a full Middesk Business. The Workflow Builder block is `Middesk`, and its service ID is `middesk_business_search`.

## Requirements

| Application field | Requirement | Notes |
| - | - | - |
| Business legal name | Required | Must be a non-empty string. |
| Formation state | Required | Must resolve to a supported state code. |

The search uses the formation state, not the business-address state.

## API flow

1. Call [Enrich Business Credit Application](/api-reference/workflow-management/enrich-business-credit-application).
2. Set `provider` to `middesk_business_search`. This service has no provider-specific request options.
3. Optionally include `stage_id`; when supplied, it must be a valid underwriting workflow-stage UUID for the application.
4. Treat `{"data":{"onqueue":true}}` as queue acceptance, not a completed search.
5. Poll [Get Commercial Data](/api-reference/workflow-management/get-commercial-data) with `services[]=middesk_business_search`.

```json theme={"system"}
{
  "provider": "middesk_business_search",
  "stage_id": "6ff8f7f6-1eb3-3525-be4a-3932c805afed"
}
```

| Data | API response path |
| - | - |
| Stored provider response | `commercial_data.middesk_business_search` |
| Lifecycle message | `statuses.middesk_business_search` |
| Stored request | `request_data.middesk_business_search` |

The API queues a background job. The provider call itself completes synchronously inside that job, after which Lendflow stores the request, response, and provider HTTP status.

## Data Orchestration availability and flow

Middesk Business Match is available in Data Orchestration under **Match > Middesk > Name Search**.

1. Add the Middesk Name Search service step.
2. Configure a condition against the best returned score, from `0` through `1`.
3. If a successful business-search prerequisite is absent, Data Orchestration runs `middesk_business_search` synchronously before evaluating the condition.
4. A template can optionally use the successful result to replace the application's business legal name with the best candidate name.

## What the service returns

| Response area | Meaning |
| - | - |
| `data` | Candidate Secretary of State business-name records. An empty array means Middesk returned no candidate. |
| Candidate identity | Registered name, state, jurisdiction, object type, and filing number. |
| `score` | Relative name-match score from `0` through `1`. Higher values indicate a closer match, but Lendflow does not define a universal approval threshold. |
| `object` and `url` | Provider response metadata when Middesk supplies it. |

## Representative response

```json theme={"system"}
{
  "data": [
    {
      "name": "EXAMPLE BUSINESS LLC",
      "state": "TX",
      "jurisdiction": "DOMESTIC",
      "object": "name",
      "file_number": "0800000001",
      "score": 0.98
    }
  ],
  "object": "list",
  "url": "/v1/names/search"
}
```

## Response attributes

| Attribute | Type | Meaning | Possible values or units | When returned |
| - | - | - | - | - |
| `data` | Array | Candidate business-name records. | Zero or more objects. | On a successful provider response. |
| `data[].name` | String | Candidate registered business name. | Provider text. | For each candidate. |
| `data[].state` | String | State associated with the candidate filing. | Two-letter state code in current models. | For each candidate when supplied. |
| `data[].jurisdiction` | String | Candidate filing's relationship to the state. | Provider-controlled text, including `DOMESTIC` or `FOREIGN` in current fixtures. | When supplied. |
| `data[].object` | String | Middesk object type for the candidate. | Provider-controlled text. | When supplied. |
| `data[].file_number` | String | Secretary of State filing identifier. | Identifier text; preserve leading zeroes. | When supplied. |
| `data[].score` | Number | Relative business-name match score. | `0` through `1`. | For each candidate in the current model. |
| `object` | String | Top-level Middesk response object type. | Provider-controlled text. | When supplied. |
| `url` | String | Provider path associated with the response. | Provider-controlled path. | When supplied. |

## Errors and statuses

* Missing `business_legal_name` or an unresolved `formation_state` fails validation before the Middesk request.
* An inactive or invalid Middesk integration prevents a successful provider call.
* Middesk HTTP errors are stored with their response body and status code, and Lendflow marks the queued job as failed.
* A successful response with `data: []` means no candidate was found; it is not a transport failure.
* `Success` means the search response was stored. It does not mean the business passed KYB verification.

## FAQ

<AccordionGroup>
  <Accordion title="Is Middesk Business Match the full Middesk KYB service?">
    No. `middesk_business_search` only returns possible business-name matches. The separate `middesk` service creates and verifies a Middesk Business.
  </Accordion>

  <Accordion title="Which state does the search use?">
    It uses the application's formation state after Lendflow resolves it to a supported state code.
  </Accordion>

  <Accordion title="What does a score of 0.98 mean?">
    It is a high relative name-match score on Middesk's `0`-through-`1` scale. Lendflow does not define one score as an automatic underwriting decision.
  </Accordion>

  <Accordion title="Can Data Orchestration update the business name?">
    Yes. When that action is configured and its condition succeeds, the template can apply the best returned candidate name to the application business.
  </Accordion>
</AccordionGroup>