Return complete business profiles with Business enrichment

A Business enrichment order is an asynchronous process similar to the synchronous Smart populate API. It returns attributes about a business and performs live scraping to achieve a higher fill rate on attributes like web analysis and industry classification.

A Business enrichment order does not verify the business. Unlike a Business Verification order, it never goes to audit and completes relatively quickly.

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/businesses/ endpoint with the business_enrichment product.
Middesk returns an id for the Business enrichment order.
Because a Business enrichment order is asynchronous, set up webhooks to receive order updates.
Middesk returns information about the business that you can use to pre-fill fields during onboarding. This information has a higher fill rate than the synchronous Smart populate API.

Create a Business enrichment order

Set up webhooks

Because Business enrichment orders are asynchronous, set up webhooks to receive notifications when the order completes. See Implement webhooks for details.

Listen for the order.updated event to know when your Business enrichment order is complete.

Create the order

Send a POST request to create a new business with the business_enrichment product:

Example request

$ curl -X POST https://api.middesk.com/v1/businesses \
>   -H "Authorization: Bearer <API KEY>" \
>   -H "Accept: application/json" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Dunder Mifflin Paper Company",
>     "orders": [
>       {
>         "product": "business_enrichment"
>       }
>     ],
>     "addresses": [
>       {
>         "full_address": "1725 Slough Avenue, Scranton, PA 18501"
>       }
>     ]
>   }'

A successful request returns a 200 OK with the Business object, including the order id:

Example response

1 {
2   "object": "business",
3   "id": "021ebab4-173c-4b6c-838a-a313d566df76",
4   "name": "Dunder Mifflin Paper Company",
5   "created_at": "2025-11-14T17:03:47.177Z",
6   "updated_at": "2025-11-14T17:03:51.546Z",
7   "status": "pending",
8   ...
9 }

Retrieve the completed order

Once you receive the webhook notification, fetch the completed Business enrichment order:

Example request

$ curl -X GET "https://api.middesk.com/v1/businesses/<id>" \
>   -H "Authorization: Bearer <API KEY>" \
>   -H "Accept: application/json"

The response contains rich business data that you can use to pre-fill onboarding fields:

Example response (truncated)

1 {
2   "object": "business",
3   "id": "021ebab4-173c-4b6c-838a-a313d566df76",
4   "name": "Dunder Mifflin Paper Company",
5   "status": "open",
6   "tin": {
7     "tin": "23-1043927",
8     "tin_type": "EIN"
9   },
10   "formation": {
11     "entity_type": "CORPORATION",
12     "formation_date": "2002-03-19"
13   },
14   "website": {
15     "url": "http://www.dundermifflin.com"
16   },
17   "names": [
18     {
19       "name": "Dunder Mifflin Paper Company",
20       "type": "legal"
21     }
22   ],
23   "addresses": [
24     {
25       "address_line1": "1725 Slough Avenue",
26       "address_line2": null,
27       "city": "Scranton",
28       "state": "PA",
29       "postal_code": "18501",
30       "full_address": "1725 Slough Avenue, Scranton, PA 18501",
31       "labels": []
32     }
33   ],
34   "people": [
35     {
36       "name": "Michael Scott",
37       "titles": [{ "title": "REGIONAL MANAGER" }],
38       "phone_numbers": [
39         {
40           "phone_number": "570-555-5555",
41           "recommended": true,
42           "contact_type": "personal"
43         }
44       ],
45       "emails": [
46         {
47           "email": "[email protected]",
48           "contact_type": "business"
49         }
50       ]
51     }
52   ],
53   "industry_classification": {
54     "status": "completed",
55     "categories": [
56       {
57         "name": "Stationery, Office Supplies, and Gift Stores",
58         "sector": "WHOLESALE_TRADE",
59         "naics_codes": ["453210"]
60       }
61     ]
62   },
63   "created_at": "2025-11-14T17:03:47.177Z",
64   "updated_at": "2025-11-14T17:03:51.546Z"
65 }

API reference

Create Business enrichment order

Method: POST

URL: https://api.middesk.com/v1/businesses

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

Request body

Parameter	Description	Required
`name`	Business name.	Yes
`addresses`	List of addresses.	Yes
`orders`	Set to `[{"product": "business_enrichment"}]`	Yes

Response statuses

Code	Description
`200`	Success
`401`	Unauthorized
`422`	Invalid parameters

Fetch Business enrichment order

Method: GET

URL: https://api.middesk.com/v1/businesses/<id>

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

Response statuses

Code	Description
`200`	Success
`401`	Unauthorized

Response schema

The response is a Business object. For Business enrichment orders, the following fields are populated:

Property	Type	Description	Guaranteed
`object`	`string`	A definition of the type of object returned	Yes
`id`	`string`	Middesk-generated unique identifier for the business	Yes
`name`	`string`	The given name for the company	Yes
`created_at`	`timestamp`	Creation timestamp	Yes
`updated_at`	`timestamp`	Last update timestamp	No
`status`	`string`	The current status of the business lifecycle	Yes
`tin`	`object`	Tax identification number details (`tin`, `tin_type`)	No
`formation`	`object`	Information about the formation of the business	Nullable
`names`	`object[]`	Details about the business names	Yes
`addresses`	`object[]`	All known addresses tied to a business entity	Yes
`orders`	`object[]`	Contains only the Business enrichment order	Yes
`people`	`object[]`	Information about people	Yes (can be an empty array)
`industry_classification`	`object`	Information about Industry Classification	Nullable
`website`	`object`	Website information	Nullable

Person

The Person object has 2 additional keys:

Property	Type	Description	Guaranteed
email_addresses	`object[]`	An array of objects	yes - can be an empty array
email_addresses[].email	`string`		yes
email_addresses[].object	`string`	”email_address”	yes
email_addresses[].contact_type	`string`	”professional” or “personal”	yes
phone_numbers	`object[]`	An array of objects	yes - can be an empty array
phone_numbers[].phone	`string`		yes
phone_numbers[].object	`string`	”phone_number”	yes
phone_numbers[].contact_type	`string`	”professional” or “personal”
phone_numbers[].recommended	`boolean`		yes

Get a demo

Contact your account manager or contact sales to inquire about access.

$	curl -X POST https://api.middesk.com/v1/businesses \
>	-H "Authorization: Bearer <API KEY>" \
>	-H "Accept: application/json" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"name": "Dunder Mifflin Paper Company",
>	"orders": [
>	{
>	"product": "business_enrichment"
>	}
>	],
>	"addresses": [
>	{
>	"full_address": "1725 Slough Avenue, Scranton, PA 18501"
>	}
>	]
>	}'

1	{
2	"object": "business",
3	"id": "021ebab4-173c-4b6c-838a-a313d566df76",
4	"name": "Dunder Mifflin Paper Company",
5	"created_at": "2025-11-14T17:03:47.177Z",
6	"updated_at": "2025-11-14T17:03:51.546Z",
7	"status": "pending",
8	...
9	}

$	curl -X GET "https://api.middesk.com/v1/businesses/<id>" \
>	-H "Authorization: Bearer <API KEY>" \
>	-H "Accept: application/json"