Return synchronous business details with Smart populate

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

A user types their business name and address, or selects the name and address from the list returned by the Autocomplete API.
Your backend sends a request to Middesk’s POST /v1/prefill/businesses endpoint.
Middesk returns real-time information about the business including:
- Names
- Addresses
- People
- Entity type
- Last 4 digits of EIN
- Website
- Industry classifications
Use the returned data to pre-fill fields during the business onboarding process.

For higher fill rates on attributes like web analysis and industry classification, use the asynchronous Business enrichment Order instead.

Integrate the Smart populate API

Prepare your request

To search for a business, provide either:

Business names and addresses, OR
Business tin

If you provide all three (names, addresses, and TIN), 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

$ 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

1 {
2   "names": [
3     {
4       "name": "Dunder Mifflin Paper Company",
5       "type": "legal"
6     }
7   ],
8   "addresses": [
9     {
10       "full_address": "1725 Slough Avenue, Scranton, PA 18501",
11       "address_line1": "1725 Slough Avenue",
12       "address_line2": null,
13       "city": "Scranton",
14       "state": "PA",
15       "postal_code": "18501",
16       "labels": ["mailing", "primary"]
17     }
18   ],
19   "tin": {
20     "tin_type": "EIN",
21     "tin": "123456789",
22     "last_four": "7890"
23   },
24   "formation": {
25     "entity_type": "CORPORATION",
26     "formation_date": "2018-03-05"
27   },
28   "industry_classifications": [
29     {
30       "name": "Paper and Paper Product Merchant Wholesalers",
31       "category": "WHOLESALE_SERVICES",
32       "naics_codes": ["4241"],
33       "classification_system": "NAICS"
34     }
35   ],
36   "people": [
37     {
38       "name": "Michael Scott",
39       "titles": ["MANAGER", "REGISTERED AGENT"]
40     },
41     {
42       "name": "David Wallace",
43       "titles": ["Chief Executive Officer"]
44     }
45   ],
46   "website": {
47     "url": "https://dunder-mifflin.netlify.app/"
48   }
49 }

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
`names`	List of business names (legal names or DBAs).	No (required if `tin` not provided)
`addresses`	List of addresses.	No (required if `tin` not provided)
`tin`	TIN for the business.	No (required if `names` and `addresses` 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 to inquire about access.