Business Enrichment Order Integration Guide

This guide walks through how to use business enrichment orders. A business enrichment order is an asynchronous process similar to the synchronous Smart Populate API . A business enrichment order returns attributes about a business, and will perform live scraping to return a much higher fill rate on attributes like web analysis and industry classification.

A business enrichment order does not do any verification of the business. Unlike a Business Verify Order, it will never go to audit, and should complete relatively quickly.

In this guide, you’ll find:

High-level design
Full API Reference

Example End-to-End Flow

A user types their business name and address.
1. Alternatively, a user selects the name and address from the list of results returned by our autocomplete API.
Your backend sends a request to Middesk's POST /v1/businesses/ endpoint, and receives back a id for the business enrichment order.
Because a business enrichment order is asynchronous, we recommend setting up webhooks to receive order updates, as described here.
Middesk returns information about the business which can be used to pre-fill fields during the business onboarding process. This information will have a higher fill rate than if you had simply queried POST /prefill/businesses.

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
names	List of business names.	Yes
addresses	List of addresses.	Yes
orders	Set to [{"product": "business_enrichment"}]	Yes

Example Request

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

Response Statuses:

Code	Description
200	Success
401	Unauthorized
422	Invalid parameters

Example Response

{
  "object": "business",
  "id": "021ebab4-173c-4b6c-838a-a313d566df76",
  "external_id": null,
  "unique_external_id": null,
  "name": "Dunder Mifflin Paper Company",
  "created_at": "2025-11-14T17:03:47.177Z",
  "updated_at": "2025-11-14T17:03:51.546Z",
  "status": "pending",
  ...
}

{  
  "error": "Unauthorized",  
  "message": "Missing or invalid API key"  
}

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

Example Request

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

Response Statuses:

Code	Description
200	Success
401	Unauthorized

Example Responses

{
  "object": "business",
  "id": "021ebab4-173c-4b6c-838a-a313d566df76",
  "external_id": null,
  "unique_external_id": null,
  "name": "Dunder Mifflin Paper Company",
  "created_at": "2025-11-14T17:03:47.177Z",
  "updated_at": "2025-11-14T17:03:51.546Z",
  "status": "open",
  "tags": [],
  "requester": {
    "id": "7981d0f9-cadc-4f93-98e2-92c6baf538f0",
    "type": "account",
    "name": "Middesk",
    "requested_at": "2025-11-14T17:03:47.204Z"
  },
  "assignee_id": "9e2843ab-0724-4c33-a970-297232891b22",
  "supported_document_types": [
    "Articles of Incorporation",
    "Certificate of Good Standing"
  ],
  "review": {
    "object": "review",
    "id": "239786ae-339c-4888-8893-3a2628f81af1",
    "created_at": "2025-11-14T17:03:47.432Z",
    "updated_at": "2025-11-14T17:03:47.432Z",
    "completed_at": null,
    "tasks": [],
    "assignee": {
      "object": "user",
      "id": "9e2843ab-0724-4c33-a970-297232891b22",
      "name": "Kurt Ruppel",
      "email": "[email protected]",
      "roles": [
        "admin"
      ],
      "image_url": "https://www.gravatar.com/avatar/adf44f0a1f65df473622c32bd09a0976?s=64&d=https%3A%2F%2Fapp.middesk.com%2Fimages%2Fdefault-avatar.png",
      "directory_managed": false,
      "last_login_at": "2025-11-10T14:05:11.508Z",
      "settings": {
        "receives_agent_emails": false
      },
      "created_at": "2018-12-14T23:23:09.531Z"
    }
  },
  "tin": {
    "name": "DUNDER MIFFLIN PAPER COMPANY",
    "mismatch": false,
    "unknown": false,
    "verified": true,
    "error": null,
    "updated_at": "2025-11-14T17:03:48.695Z",
    "issued": true,
    "verified_by": "business",
    "tin_type": "EIN",
    "business_id": "021ebab4-173c-4b6c-838a-a313d566df76",
    "tin": "123456789"
  },
  "business_batch_id": null,
  "formation": {
    "entity_type": "CORPORATION",
    "formation_date": "2002-03-19",
    "formation_state": "PA",
    "created_at": "2025-11-14T17:03:48.053Z",
    "updated_at": "2025-11-14T17:03:48.053Z",
    "sources": [
      {
        "id": "f44ef749-5ff2-45a8-9d3c-9de88c945497",
        "type": "registration",
        "metadata": {
          "state": "PA",
          "status": "active",
          "file_number": "C3433161",
          "jurisdiction": "DOMESTIC"
        }
      }
    ]
  },
  "website": {
    "object": "website",
    "id": "449861c9-de63-45fc-b2ed-9f482dbe4813",
    "url": "http://www.dundermifflin.com",
    "created_at": "2025-11-14T17:03:48.710Z",
    "updated_at": "2025-11-14T17:03:48.846Z",
    "business_id": "021ebab4-173c-4b6c-838a-a313d566df76"
  },
  "watchlist": null,
  "bankruptcies": [],
  "documents": [],
  "liens": [],
  "names": [
    {
      "object": "name",
      "id": "3ff0b29b-3943-4477-9112-6603667f5f9c",
      "name": "Dunder Mifflin Paper Company",
      "submitted": true,
      "type": "legal",
      "business_id": "021ebab4-173c-4b6c-838a-a313d566df76",
      "sources": [
        {
          "id": "f44ef749-5ff2-45a8-9d3c-9de88c945497",
          "type": "registration",
          "metadata": {
            "state": "PA",
            "status": "active",
            "file_number": "C3433161",
            "jurisdiction": "DOMESTIC"
          }
        }
      ]
    }
  ],
  "addresses": [
    {
      "object": "address",
      "address_line1": "1725 Slough Avenue",
      "address_line2": null,
      "city": "Scranton",
      "state": "PA",
      "postal_code": "18501",
      "full_address": "1725 Slough Avenue, Scranton, PA 18501",
      "submitted": true,
      "id": "31220781-a589-4378-9dca-04ff1fbe5504",
      "latitude": 41.4094,
      "longitude": -75.6624,
      "property_type": "COMMERCIAL",
      "deliverable": true,
      "deliverability_analysis": null,
      "street_view_available": true,
      "labels": [
        "physical"
      ],
      "created_at": "2025-11-14T17:03:47.192Z",
      "updated_at": "2025-11-14T17:03:47.459Z",
      "registered_agent_name": null,
      "cmra": false,
      "business_id": "021ebab4-173c-4b6c-838a-a313d566df76",
      "location_count": null,
      "is_registered_agent": null,
      "sources": [
        {
          "id": "f44ef749-5ff2-45a8-9d3c-9de88c945497",
          "type": "registration",
          "metadata": {
            "state": "PA",
            "labels": [
              "mailing", "physical"
            ],
            "status": "active",
            "file_number": "C3433161",
            "jurisdiction": "DOMESTIC"
          }
        }
      ],
      "rating": {
        "risk_rating": "not_available"
      }
    }
  ],
  "people": [
    {
      "object": "person",
      "name": "Michael Scott",
      "submitted": false,
      "business_id": "021ebab4-173c-4b6c-838a-a313d566df76",
      "sources": [
        {
          "id": "f44ef749-5ff2-45a8-9d3c-9de88c945497",
          "type": "registration",
          "metadata": {
            "state": "PA",
            "status": "active",
            "file_number": "C3433161",
            "jurisdiction": "DOMESTIC"
          }
        }
      ],
      "titles": [
        {
          "object": "person_title",
          "title": "REGIONAL MANAGER"
        }
      ],
      "people_bankruptcies": []
    }
  ],
  "phone_numbers": [],
  "profiles": [
    {
      "object": "profile",
      "type": "google",
      "id": "a277e035-15c6-4197-bc9a-88354b9c7f15",
      "external_id": "5656850906825484336",
      "url": "https://maps.google.com/?cid=5656850906825484336",
      "metadata": {
        "full_address": "1725 Slough Avenue, Scranton, PA 18501",
        "name": "Dunder Mifflin Paper Company",
        "website_urls": [
          "http://www.dundermifflin.com"
        ],
        "latitude": 41.4094,
        "longitude": -75.6624,
        "phone_number": "(570) 555-0123",
        "categories": [
          "Office supply store"
        ],
        "reviews": [
          {
            "text": "Great paper products and excellent customer service.",
            "rating": 5,
            "posted_at": "2021-01-28T20:40:56.051Z"
          }
        ]
      },
      "rating": 4.5,
      "rating_count": 1
    }
  ],
  "registrations": [
    {
      "object": "registration",
      "id": "f44ef749-5ff2-45a8-9d3c-9de88c945497",
      "business_id": "021ebab4-173c-4b6c-838a-a313d566df76",
      "name": "DUNDER MIFFLIN PAPER COMPANY",
      "status": "active",
      "sub_status": "GOOD_STANDING",
      "status_details": "Active",
      "jurisdiction": "DOMESTIC",
      "entity_type": "CORPORATION",
      "file_number": "3433161",
      "addresses": [
        "1725 SLOUGH AVENUE, SCRANTON, PA 18501"
      ],
      "officers": [
        {
          "name": "MICHAEL SCOTT",
          "roles": [
            "Regional Manager"
          ]
        }
      ],
      "registered_agent": {
        "name": "MICHAEL SCOTT"
      },
      "registration_date": "2002-03-19",
      "state": "PA",
      "source": "https://www.corporations.pa.gov/search/corpsearch"
    }
  ],
  "orders": [
    {
      "object": "order",
      "id": "fba28f2e-dca7-4ab3-b05e-3172b79b9ee3",
      "business_id": "021ebab4-173c-4b6c-838a-a313d566df76",
      "completed_at": "2025-11-14T17:03:51.492Z",
      "created_at": "2025-11-14T17:03:47.204Z",
      "monitoring": false,
      "product": "business_enrichment",
      "package": "business_enrichment",
      "requester": {
        "name": "Middesk",
        "type": "account"
      },
      "status": "completed",
      "subproducts": [],
      "updated_at": "2025-11-14T17:03:51.845Z"
    }
  ],
  "document_verifications": [],
  "industry_classification": {
    "object": "industry_classification",
    "id": "7befbeca-083b-4db8-8440-ea20114c2493",
    "status": "completed",
    "categories": [
      {
        "classification_system": "NAICS",
        "name": "Stationery, Office Supplies, and Gift Stores",
        "sector": "RETAIL_TRADE",
        "category": "STATIONERY_OFFICE_SUPPLIES_AND_GIFT_STORES",
        "score": 0.95,
        "high_risk": false,
        "naics_codes": [
          "453210"
        ],
        "sic_codes": [
          "5943"
        ],
        "mcc_codes": [],
        "prohibited_labels": []
      }
    ],
    "created_at": "2025-11-14T17:03:51.413Z",
    "completed_at": "2025-11-14T17:03:51.464Z"
  },
  "monitor": {
    "object": "monitor",
    "id": "8ff0ec32-0a23-4a98-b240-9b9d6f15d889",
    "created_at": "2025-11-14T17:03:47.220Z",
    "event_types": [
      {
        "enabled_at": null,
        "status": "unavailable",
        "type": "tin.retrieved"
      }
    ]
  },
  "tax_exempt_organization": null,
  "fmcsa_registrations": [],
  "litigations": [],
  "actions": [],
  "policy_results": [],
  "politically_exposed_person_screening": null,
  "adverse_media_screening": null,
  "signal": null,
  "submitted": {
    "object": "submitted_attributes",
    "name": "Dunder Mifflin Paper Company",
    "entity_type": null,
    "addresses": [
      {
        "full_address": "1725 Slough Avenue, Scranton, PA 18501"
      }
    ],
    "orders": [
      {
        "package": "business_enrichment",
        "product": "business_enrichment"
      }
    ],
    "people": [],
    "phone_numbers": [],
    "email_addresses": null,
    "tags": null,
    "external_id": null,
    "unique_external_id": null,
    "tin": null,
    "website": {},
    "assignee_id": null,
    "formation": null,
    "names": null
  }
}

{  
  "error": "Unauthorized",  
  "message": "Missing or invalid API key"  
}

Response Schema

The response schema will be a Business. However, you can expect that only the following fields are populated, as the Business Enrichment order does not perform the same verification as a Business Verify order does:

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
external_id	`string`	Identifier from non-Middesk system	no - populated if external_id was provided when creating the business
unique_external_id	`string`	Unique identifier from non-Middesk system. If a new business is created using the same `unique_external_id`, Middesk will not create that business. This can be used to prevent duplicate businesses	no
name	`string`	The given name for the company	yes
created_at	`timestamp`		yes
updated_at	`timestamp`		no
status	`string`	The current status of the business lifecycle.	yes
tin	`object`	Information about the employer identification number	no
formation	`object`	Information about the formation of the business	nullable
registrations	`object[]`	List and details of all known registrations	yes - can be an empty array if no registrations found for the business
names	`object[]`	Details about the business names	yes
addresses	`object[]`	All known addresses tied to a business entity.	yes
review	`object`	The business Review.	yes - will be empty until the business moves to `in_review`, `approved`, or `rejected`
orders	`object[]`	Will only include the Business Enrichment Order	yes
people	`object[]`	Information about people	yes - can be an empty array
profiles	`object[]`	Information about profile	yes - can be an empty array
industry_classification	`object`	Information about Industry Classification	nullable
tags	`string[]`	Custom tags that can be added to a Business at creation for analytics, tracking, and various other use cases.	yes - can be an empty array
website	`object`	Website information	nullable

You will not receive the following attributes of the business: policy_results, watchlist, liens, documents adverse_media_screening, phone_numbers, politically_exposed_person_screening, monitor, bankruptcies, document_verifications, tax_exempt_organization, fmcsa_registrations.