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

# Return synchronous business details with Smart populate

> Use the Smart populate API to return real-time data about a business for pre-filling onboarding fields.

The Smart populate API (`/prefill/businesses`) returns real-time data about a business that you can use to pre-fill fields during the onboarding process. This synchronous API provides instant responses with business names, addresses, people, entity type, TIN, website, and industry classifications.

## End-to-end flow

1. A user types their business name and address, or selects a business from the list returned by the [Autocomplete API](/accelerate-onboarding/autocomplete).
2. Your backend sends a request to Middesk's `POST /v1/prefill/businesses` endpoint. If the user selected a result from Autocomplete, pass the `autocomplete_result_id` for consistent business resolution.
3. Middesk returns real-time information about the business including:
   * Names
   * Addresses
   * People
   * Entity type
   * EIN (unmasked or masked to last 4 digits)
   * Website
   * Industry classifications
4. Use the returned data to pre-fill fields during the business onboarding process.

> **Note**
>
> For higher fill rates on attributes like web analysis and industry classification, use the asynchronous [Business enrichment order](/accelerate-onboarding/business-enrichment) instead.

## Integrate the Smart populate API

#### Prepare your request

To search for a business, provide one of:

* `autocomplete_result_id` from a previous [Autocomplete API](/accelerate-onboarding/autocomplete) response (recommended when the user selected a result from autocomplete), OR
* Business `names` and `addresses`, OR
* Business `tin`

If you provide `autocomplete_result_id`, the API performs a direct lookup using the selected identity. If you provide names, addresses, and TIN together, the API only searches by names and addresses.

#### Make a Smart populate request

Send a POST request to the prefill endpoint with the business name and address:

**`Example request (with autocomplete result)`**

```bash title="Example request (with autocomplete result)"
curl -X POST "https://api.middesk.com/v1/prefill/businesses" \
  -H "Authorization: Bearer <API KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "autocomplete_result_id": "35a0fe9a-6586-4d27-a980-c4c09511e273"
  }'
```

**`Example request (with name and address)`**

```bash title="Example request (with name and address)"
curl -X POST "https://api.middesk.com/v1/prefill/businesses" \
  -H "Authorization: Bearer <API KEY>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "names": ["Dunder Mifflin Paper Company"],
    "addresses": ["1725 Slough Avenue, Scranton, PA 18501"]
  }'
```

A successful request returns a `200 OK` with business data in the response body:

**`Example response`**

```json title="Example response"
{
  "names": [
    {
      "name": "Dunder Mifflin Paper Company",
      "type": "legal"
    }
  ],
  "addresses": [
    {
      "full_address": "1725 Slough Avenue, Scranton, PA 18501",
      "address_line1": "1725 Slough Avenue",
      "address_line2": null,
      "city": "Scranton",
      "state": "PA",
      "postal_code": "18501",
      "labels": ["mailing", "primary"]
    }
  ],
  "tin": {
    "tin_type": "EIN",
    "tin": "123456789",
    "last_four": "7890"
  },
  "formation": {
    "entity_type": "CORPORATION",
    "formation_date": "2018-03-05"
  },
  "industry_classifications": [
    {
      "name": "Paper and Paper Product Merchant Wholesalers",
      "category": "WHOLESALE_SERVICES",
      "naics_codes": ["4241"],
      "classification_system": "NAICS"
    }
  ],
  "people": [
    {
      "name": "Michael Scott",
      "titles": ["MANAGER", "REGISTERED AGENT"]
    },
    {
      "name": "David Wallace",
      "titles": ["Chief Executive Officer"]
    }
  ],
  "website": {
    "url": "https://dunder-mifflin.netlify.app/"
  }
}
```

> **Note**
>
> The API returns `null` if no business is found.

#### Use the data to pre-fill your forms

Map the returned data to the appropriate fields in your onboarding forms:

* Use `names` for the business name field
* Use `addresses` for address fields
* Use `formation.entity_type` for entity type selection
* Use `people` to pre-populate owner or officer fields
* Use `tin.last_four` to verify TIN input

## API reference

**Method**: `POST`

**URL**: `https://api.middesk.com/v1/prefill/businesses`

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

### Request body

| Parameter                | Description                                                                | Required                                                                       |
| :----------------------- | :------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
| `autocomplete_result_id` | ID from an [Autocomplete API](/accelerate-onboarding/autocomplete) result. | No                                                                             |
| `names`                  | List of business names (legal names or DBAs).                              | No (required if `tin` and `autocomplete_result_id` not provided)               |
| `addresses`              | List of addresses.                                                         | No (required if `tin` and `autocomplete_result_id` not provided)               |
| `tin`                    | TIN for the business.                                                      | No (required if `names`/`addresses` and `autocomplete_result_id` not provided) |

### Response statuses

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

### Response schema

| Field                      | Type                  | Description                               |
| :------------------------- | :-------------------- | :---------------------------------------- |
| `names`                    | `Name[]`              | Array of associated names.                |
| `addresses`                | `Address[]`           | Array of associated addresses.            |
| `people`                   | `Person[]`            | Array of associated people.               |
| `formation`                | `Formation` or `null` | Formation information for the business.   |
| `industry_classifications` | `Classification[]`    | Industry Classification for the business. |
| `tin`                      | `TIN` or `null`       | TIN for the business.                     |
| `website`                  | `Website` or `null`   | Website for the business.                 |

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

| 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. |

### Person object

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

### Formation object

| Field            | Type     | Description                                                                                                                                                   |
| :--------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `entity_type`    | `string` | The legal structure of the entity. Possible values: `LLC`, `CORPORATION`, `NON_PROFIT`, `PARTNERSHIP`, `TRUST`, `SOLE PROPRIETORSHIP`, `AGENT`, and `UNKNOWN` |
| `formation_date` | `date`   | Formation date of the business.                                                                                                                               |

### TIN object

| Field       | Type     | Description                  |
| :---------- | :------- | :--------------------------- |
| `tin_type`  | `string` | Type of TIN. Value: `EIN`    |
| `tin`       | `string` | Full TIN.                    |
| `last_four` | `string` | Last four digits of the TIN. |

### Website object

| Field | Type     | Description                              |
| :---- | :------- | :--------------------------------------- |
| `url` | `string` | The URL of the website for the business. |

### Classification object

| Field                   | Type               | Description                          |
| :---------------------- | :----------------- | :----------------------------------- |
| `name`                  | `string`           | Name of the classification.          |
| `sector`                | `string` or `null` | Sector of the classification.        |
| `naics_codes`           | `string[]`         | List of NAICS codes.                 |
| `classification_system` | `string`           | Classification system. Value `NAICS` |

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

> Use the Smart populate API to return real-time data about a business for pre-filling onboarding fields.