# Match Businesses
Match a list of businesses attributes to ids.
Returns a list of the same length and order as the input list, with the matched ids.
### **Endpoint:`POST /businesses/match`**
### **Description**
The **Match Businesses** endpoint is the **first step** in the data enrichment process. It enables users to accurately identify businesses based on their **name or domain**, returning a **unique Business ID** that acts as the **foundation for all subsequent API interactions**.
This endpoint is designed to provide **high-accuracy business matching** by leveraging **multiple data sources, validation layers, and proprietary algorithms** to ensure precise identification.
Once a business is successfully matched, its **Business ID** becomes the **primary key** for retrieving enriched company data, accessing financial insights, monitoring real-time business events, and performing additional analytics through other Explorium APIs.
Coverage
| Attribute | Coverage Details |
| --------------------- | -------------------------------------------------------------- |
| **Total Businesses** | 80M+ businesses across 150+ countries |
| **Matching Accuracy** | Advanced entity resolution for precise business identification |
| **Real-Time Updates** | Ensures the latest business records are used for matching |
How It Works
* **Input:** A list of business identifiers, which can include **name**, **domain**, and **LinkedIn company URL**.
* **Processing:** Our system cross-references multiple datasets to find the best match.
* **Output:** A structured response with the matched **Business IDs**, maintaining the same order as the input list.
Schema Explanation
| Field | Type | Description |
| --------------------- | ------ | -------------------------------------------------------------------------- |
| `businesses_to_match` | Array | List of business identifiers to match (can include name, domain, LinkedIn) |
| `name` | String | Business name provided for matching |
| `domain` | String | Business domain provided for matching |
| `linkedin_url` | String | LinkedIn company profile URL (optional, improves matching accuracy) |
| `business_id` | String | Unique identifier for the matched business (null if not found) |
Body Params – Example with LinkedIn URL
```json
{
"request_context": {
"seller_id": "sample_seller"
},
"businesses_to_match": [
{
"name": "microsoft",
"linkedin_url": "https://linkedin.com/company/microsoft"
}
]
}
```
Best Practices
* **Always store the Business ID** – It serves as the key for all future enrichment and analytics.
* **Use multiple identifiers** (e.g., name + domain, or LinkedIn URL) for **higher match accuracy**.
* **Batch requests efficiently** to optimize API performance.
* **Handle null values gracefully** to account for unmatched businesses.
* **Update and validate input data regularly** to ensure the most accurate matches.
📌 _For detailed endpoint explanations, request examples, and integration tips, explore the documentation sections above._
**Body Params - Try Me Example**
```
name: Apple
domain: apple.com
name: Microsoft
domain: microsoft.com
```
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Partner Service",
"version": "0.2.94"
},
"servers": [
{
"url": "https://api.explorium.ai",
"description": "AgentSource Server"
}
],
"paths": {
"/v1/businesses/match": {
"post": {
"tags": [
"Businesses"
],
"summary": "Match Businesses",
"description": "Match a list of businesses attributes to ids.\nReturns a list of the same length and order as the input list, with the matched ids.",
"operationId": "match_businesses",
"requestBody": {
"content": {
"application/json": {
"schema": {
"properties": {
"request_context": {
"type": "object",
"title": "Request Context"
},
"businesses_to_match": {
"items": {
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"title": "Name"
},
"domain": {
"type": "string",
"title": "Domain"
},
"url": {
"type": "string",
"title": "Url"
}
},
"type": "object",
"title": "BusinessMatchInput",
"x-readme-ref-name": "BusinessMatchInput"
},
"type": "array",
"maxItems": 50,
"minItems": 1,
"title": "Businesses To Match"
}
},
"additionalProperties": false,
"type": "object",
"required": [
"businesses_to_match"
],
"title": "BusinessesMatchRequest",
"x-readme-ref-name": "BusinessesMatchRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"properties": {
"response_context": {
"properties": {
"correlation_id": {
"type": "string",
"title": "Correlation Id"
},
"request_status": {
"type": "string",
"enum": [
"success",
"miss",
"failure"
],
"title": "RequestStatus",
"description": "An enumeration.",
"x-readme-ref-name": "RequestStatus"
},
"time_took_in_seconds": {
"type": "number",
"title": "Time Took In Seconds"
}
},
"type": "object",
"required": [
"correlation_id",
"request_status",
"time_took_in_seconds"
],
"title": "ResponseContext",
"x-readme-ref-name": "ResponseContext"
},
"total_results": {
"type": "integer",
"exclusiveMinimum": 0,
"title": "Total Results",
"description": "The total_results number matched businesses"
},
"total_matches": {
"type": "integer",
"minimum": 0,
"title": "Total Matches",
"description": "The total number of matches."
},
"matched_businesses": {
"items": {
"properties": {
"input": {
"properties": {
"name": {
"type": "string",
"maxLength": 256,
"title": "Name"
},
"domain": {
"type": "string",
"title": "Domain"
},
"url": {
"type": "string",
"title": "Url"
}
},
"type": "object",
"title": "BusinessMatchInput",
"x-readme-ref-name": "BusinessMatchInput"
},
"business_id": {
"type": "string",
"pattern": "^[a-f0-9]{32}$",
"title": "Business Id"
}
},
"type": "object",
"required": [
"input"
],
"title": "BusinessMatchOutput",
"x-readme-ref-name": "BusinessMatchOutput"
},
"type": "array",
"title": "Matched Businesses",
"description": "A list of all businesses. If they not matched `business_id` will None.",
"default": []
}
},
"type": "object",
"required": [
"response_context",
"total_results",
"total_matches"
],
"title": "BusinessesMatchResponse",
"description": "This is base response model for all responses in partner service. ",
"x-readme-ref-name": "BusinessesMatchResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError",
"x-readme-ref-name": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError",
"x-readme-ref-name": "HTTPValidationError"
}
}
}
}
},
"security": [
{
"APIKeyHeader": []
},
{
"APIKeyHeader": []
}
]
}
}
},
"components": {
"securitySchemes": {
"APIKeyHeader": {
"type": "apiKey",
"in": "header",
"name": "api_key"
}
}
},
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true
}
}
```