> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.middesk.com/accelerate-onboarding/autocomplete/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server.

# Autocomplete business names and addresses

> Use the Business Identities Autocomplete API to return real-time, structured autocomplete suggestions based on partial business names.

The Business Identities Autocomplete API returns real-time, structured autocomplete suggestions based on partial business names. Use it to help users quickly find and select their business during onboarding.

## End-to-end flow

1. A user types a partial business name in your application (for example, "dunder").
2. Your frontend sends a request to Middesk's `POST /v1/identities/autocomplete` endpoint using a Publishable API key.
3. Middesk returns a list of structured business identity suggestions, each with a unique `id`, along with names, addresses, people, and entity type.
4. Your frontend renders the results in the user's UI.
5. Once a user selects the correct business, pass the `id` from the selected result to the [Smart populate](/accelerate-onboarding/smart-populate) endpoint (as `autocomplete_result_id`). Using the `id` ensures consistent business resolution between Autocomplete and Smart populate. You can also create a [Business enrichment Order](/accelerate-onboarding/business-enrichment) request to retrieve additional business attributes.

> **Note**
>
> Smart populate is a synchronous API, while a Business enrichment Order is asynchronous and offers higher coverage for certain business attributes.

## Security requirements

To ensure the integrity and appropriate use of this API:

* **Publishable API key authentication**: Each request must include a Middesk Publishable API key via the `Authorization: Bearer` header.
* **KYC enforcement**: Perform KYC checks prior to querying Middesk when possible.
* **Abuse prevention**: Prevent automated abuse or excessive velocity and volume (for example, bots or scraping).

## Integrate the Autocomplete API

#### Locate your Publishable API key

Publishable API keys are available in the [Middesk Dashboard](https://app.middesk.com):

* Use the **Publishable Test API Key** for sandbox testing
* Use the **Publishable Live API Key** for Production

Include the Publishable API key in the `Authorization` header using Bearer authorization:

```
Authorization: Bearer <API_KEY>
```

#### Make an autocomplete request

Send a POST request to the autocomplete endpoint with the business name and optional address or entity type:

**`Example request`**

```bash title="Example request"
curl -X POST "https://api.middesk.com/v1/identities/autocomplete" \
  -H "Authorization: Bearer <PUBLISHABLE API KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dunder Mif",
    "entity_type": "CORPORATION",
    "addresses": [
      {
        "address_line1": "1725 Slough Avenue",
        "city": "Scranton",
        "state": "PA",
        "postal_code": "18501"
      }
    ]
  }'
```

A successful request returns a `200 OK` with a list of business identity suggestions in the response body.

**`Example response`**

```json title="Example response"
{
  "data": [
    {
      "id": "35a0fe9a-6586-4d27-a980-c4c09511e273",
      "names": [
        { "name": "Dunder Mifflin", "type": "legal" },
        { "name": "Dunder Mifflinfinity", "type": "dba" }
      ],
      "addresses": [
        {
          "full_address": "1725 Slough Avenue, Suite 200, Scranton, PA 18505",
          "labels": ["office"]
        }
      ],
      "people": [
        { "name": "David Wallace" },
        { "name": "Robert Kazamakis" },
        { "name": "Jolene Bennett" }
      ],
      "entity_type": "CORPORATION"
    }
  ]
}
```

#### Send a follow-up request for additional data

Once a user selects a business from the autocomplete results, pass the `id` from the selected result to retrieve additional business attributes:

* Use [Smart populate](/accelerate-onboarding/smart-populate) for a synchronous response — pass the `id` as `autocomplete_result_id` to ensure consistent business resolution
* Use [Business enrichment Orders](/accelerate-onboarding/business-enrichment) for higher coverage on attributes like web analysis and industry classification

## Latency benchmarks

| Metric      | Target   |
| :---------- | :------- |
| p95 latency | \< 300ms |
| p99 latency | \< 650ms |

Performance is monitored, and alerts trigger if p95 latency exceeds 300ms over sustained periods.

## API reference

**Method**: `POST`

**URL**: `https://api.middesk.com/v1/identities/autocomplete`

**Headers**: Include the API key in the `Authorization` header using Bearer authorization

### Request body

| Parameter     | Description                                                      | Required |
| :------------ | :--------------------------------------------------------------- | :------- |
| `name`        | Partial or full business name. Minimum of 3 characters required. | Yes      |
| `addresses`   | List of addresses associated with the business.                  | No       |
| `people`      | List of people associated with the business.                     | No       |
| `entity_type` | Entity type of the business.                                     | No       |

### Address object

| Parameter       | Description           | Required |
| :-------------- | :-------------------- | :------- |
| `address_line1` | First line of address | No       |
| `state`         | State                 | No       |
| `city`          | City                  | No       |
| `postal_code`   | Postal code           | No       |

### Person object

| Parameter | Description                    | Required |
| :-------- | :----------------------------- | :------- |
| `name`    | Full name of associated person | No       |

### Response statuses

| Code  | Description         |
| :---- | :------------------ |
| `200` | Success             |
| `401` | Unauthorized        |
| `422` | Invalid parameters  |
| `429` | Rate limit exceeded |

### Response schema

| Field  | Type                 | Description                   |
| :----- | :------------------- | :---------------------------- |
| `data` | `BusinessIdentity[]` | Array of business identities. |

### BusinessIdentity object

| Field         | Type               | Description                                                                                                                                                    |
| :------------ | :----------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`          | `string`           | Unique identifier for this autocomplete result. Pass this value as `autocomplete_result_id` to the Smart populate endpoint for consistent business resolution. |
| `names`       | `Name[]`           | Array of name records for the business. Up to 3 results returned.                                                                                              |
| `addresses`   | `Address[]`        | Array of known addresses for the business. Up to 3 results returned.                                                                                           |
| `people`      | `Person[]`         | Array of associated people. Up to 3 results returned.                                                                                                          |
| `entity_type` | `string` or `null` | The legal structure of the entity. Possible values: `LLC`, `CORPORATION`, `NON_PROFIT`, `PARTNERSHIP`, `TRUST`, `SOLE PROPRIETORSHIP`, `AGENT`, and `UNKNOWN`  |

### Name object

| Field  | Type     | Description                                      |
| :----- | :------- | :----------------------------------------------- |
| `name` | `string` | A name associated with the business.             |
| `type` | `string` | The name type. Possible values: `dba` or `legal` |

### Address object (response)

| Field           | Type               | Description                                                                                                                              |
| :-------------- | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
| `full_address`  | `string`           | Full normalized address.                                                                                                                 |
| `address_line1` | `string` or `null` | First line of address.                                                                                                                   |
| `address_line2` | `string` or `null` | Second line of address.                                                                                                                  |
| `city`          | `string` or `null` | City.                                                                                                                                    |
| `state`         | `string` or `null` | State.                                                                                                                                   |
| `postal_code`   | `string` or `null` | Postal code.                                                                                                                             |
| `labels`        | `string[]`         | Labels applied to the address. Possible values: `billing`, `mailing`, `office`, `officer`, `primary`, `registered_agent`, and `shipping` |

### Person object

| Field    | Type       | Description                            |
| :------- | :--------- | :------------------------------------- |
| `name`   | `string`   | Full name of associated person.        |
| `titles` | `string[]` | List of titles associated with person. |

> **Get a demo**
>
> Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.

> Use the Business Identities Autocomplete API to return real-time, structured autocomplete suggestions based on partial business names.