Smart Populate API Integration Guide

This guide walks through how to integrate with /prefill/businesses API, which returns real-time data about a business.

You’ll find:

High-level design
Rate limits and performance expectations
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/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
Which can be used to prefill fields during the business onboarding process.

Latency Benchmarks

Metric	Target
p95 latency	< 600ms
p99 latency	< 900ms

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.	No
addresses	List of addresses.	No
TIN	TIN for the business	No

API Validation

To search for a business, either names and address are required OR TIN is required. The endpoint will search by whichever input is provided. If names, addresses, and TIN are all provided, the API will only search by names and addresses.

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"]
  }'

Response Statuses:

Code	Description
200	Success
401	Unauthorized
422	Invalid parameters
429	Rate limit exceeded

Example Responses

{
  "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",
    "last_four": "7890"
  },
  "formation": {
    "entity_type": "CORPORATION"
  },
  "industry_classifications": [
    {
      "name": "Paper and Paper Product Merchant Wholesalers",
      "score": 0.7805803271428109,
      "sector": null,
      "source": "refuel_llm",
      "category": "WHOLESALE_SERVICES",
      "high_risk": false,
      "mcc_codes": [],
      "sic_codes": [],
      "naics_codes": ["4241"],
      "prohibited_labels": [],
      "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/"
  }
}

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

{  
  "error": "Invalid request",  
  "message": "Missing required query parameter: name"  
}

{  
  "error": "Rate limit exceeded",  
  "message": "Too many requests in a short period of time"  
}

null

The API will return null if no business is found.

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`\| null	Formation information for the business.
`industry_classifications`	`Classification[]`	Industry Classification for the business.
`tin`	`TIN` \| null	TIN for the business.
`website`	`Website`\| null	Website for the business.

Name

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

Address

Field	Type	Description
`full_address`	string	Full normalized address.

Person

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

Formation

Field	Type	Description
`entity_type`	string	The legal structure of the entity. Possible values: `LLC`, `CORPORATION`, `NON_PROFIT`, `PARTNERSHIP` , and `TRUST`.

TIN

Field	Type	Description
`tin_type`	string	`EIN`
`last_four`	string	last four digits of the TIN.

Website

Field	Type	Description
`url`	string	The url of the website for the business.

Classifications

Detailed description of the classification object can be found here .