Autocomplete API Integration Guide

This guide walks through how to integrate with Middesk’s Business Identities Autocomplete API, which returns real-time, structured autocomplete suggestions based on partial business names.

You’ll find:

• High-level design and security requirements
• Step-by-step integration instructions
• Rate limits and performance expectations
• Full API Reference

Example End-to-End Flow

1. A user types a partial business name in your application (e.g., "dunder").

2. Your frontend sends a request to Middesk's POST /v1/identities/autocomplete endpoint using a Publishable API key.

3. Middesk returns a list of structured business identity suggestions:

   • Names
   • Addresses
   • People
   • Entity type

4. Your frontend renders the results in the user's UI.

5. Once a user selects the correct business, send a Smart Populate request or a Business Enrichment Order request to Middesk, to retrieve additional business attributes that can be used to pre-populate fields for the user and streamline the onboarding flow.

   1. Smart Populate is a synchronous API, while a Business Enrichment Order is asynchronous, and offers higher coverage for certain business attributes.

Security Requirements

To ensure the integrity and appropriate use of this API:

• Publishable API key authentication: Each request must include a Middesk Publishable API key via the Authorization: Bearer header.
• KYC enforcement: You should perform KYC checks prior to querying Middesk when possible.
• Abuse prevention: You are responsible for preventing automated abuse or excessive velocity and volume (e.g., bots, scraping).

Integration Instructions

Step 1: Locate Your Publishable API Key

A Publishable API is needed to authenticate requests:

• Publishable API keys are available in the Middesk Dashboard
• Use the "Publishable Test API Key" for sandbox testing
• Use the "Publishable Live API Key" for production
• Include the Publishable API key in the Authorization header using Bearer authorization:

Authorization: Bearer <API_KEY>

Refer to Middesk’s Getting Started Guide for more detail.

Step 2: Make an Autocomplete Request

curl -X POST "https://api.middesk.com/v1/identities/autocomplete" \
  -H "Authorization: Bearer <PUBLISHABLE API KEY>" \
  -H "Content-Type: application/json" \
  -d '{
	"name": "Dunder Mif",
	"entity_type": "CORPORATION",
	"addresses": [
		{
			"address_line1": "1725 Slough Avenue",
			"city": "Scranton",
			"state": "PA",
			"postal_code": "18501"
		}
	]
}'

A successful request returns a 200 OK with a list of business identity suggestions in the response body. Refer to the API Reference below for more detail.

Latency Benchmarks

Performance is monitored and alerts are triggered if p95 latency exceeds 300ms over sustained periods.

API Reference

Method: POST

URL: https://api.middesk.com/v1/identities/autocomplete

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

Request body:

Address body

Example Request

curl -X POST "https://api.middesk.com/v1/identities/autocomplete" \
  -H "Authorization: Bearer <PUBLISHABLE API KEY>" \
  -H "Content-Type: application/json" \
  -d '{
	"name": "Dunder Mif",
	"entity_type": "CORPORATION",
	"addresses": [
		{
			"address_line1": "1725 Slough Avenue",
			"city": "Scranton",
			"state": "PA",
			"postal_code": "18501"
		}
	]
}'

Response Statuses:

Example Responses

{
  "data": [
    {
      "names": [
        { "name": "Dunder Mifflin", "type": "legal" },
        { "name": "Dunder Mifflinfinity", "type": "dba" } 
      ],
      "addresses": [
        {
          "full_address": "1725 Slough Avenue, Suite 200, Scranton, PA 18505",
					"labels": ["office"]
				}
      ],
      "people": [
        { "name": "David Wallace" },
        { "name": "Robert Kazamakis" },
        { "name": "Jolene Bennett" } 
			],
      "entity_type": "COPRPORATION"
    }
  ]
}

{  
  "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"  
}

Response Schema

BusinessIdentity

Name

Address

Person