> ## Documentation Index
> Fetch the complete documentation index at: https://leadmagic.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Company Lookalike
> Find similar companies from a seed domain or description with full company output.
# Company Lookalike
`POST /v3/companies/lookalike` finds similar companies from a seed domain, website, or text description. It returns the same full company output row as [Company Search](/docs/v1/reference/company-search), plus lookalike scoring fields when available.
## Endpoint Details
| Metric | Value |
| -------------- | --------------------------------------------------- |
| **Cost** | **5 credits** when lookalike companies are returned |
| **No Results** | **FREE** |
Lookalike requests return full company rows, so you usually do not need a second lookup for each result.
| Metric | Value |
| ------------------- | --------------------------- |
| **Requests/Minute** | 500 |
| **Burst Capacity** | Subject to workspace limits |
***
## Quick Example
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST 'https://api.leadmagic.io/v3/companies/lookalike' \
-H 'X-API-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"company_domain": "leadmagic.io",
"company_filters": {
"country_codes": ["US"],
"employee_ranges": ["51 to 200", "201 to 500"],
"has_tech_stack": true
},
"limit": 25
}'
```
```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://api.leadmagic.io/v3/companies/lookalike', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
company_domain: 'leadmagic.io',
company_filters: {
country_codes: ['US'],
employee_ranges: ['51 to 200', '201 to 500'],
has_tech_stack: true
},
limit: 25
})
});
const data = await response.json();
console.log(`${data.count} lookalike companies found`);
```
## Request Body
Provide either a seed domain/website or a text description.
Seed company domain. Preferred for strongest vector lookalike matching.
Alias for `company_domain`.
Seed website URL or domain. Normalized to a domain.
Optional seed object. Supports `seed.domain`, `seed.domains`, and `seed.description`.
Free-text company description to embed for lookalike discovery when you do not have a seed domain.
Seed company name used as text intent when no domain is supplied. Domains are more precise.
Same full company filter family as [Company Search](/docs/v1/reference/company-search), applied after vector similarity.
Number of lookalike companies to return. Maximum is `2000`.
Offset for pagination.
## Response
Human-readable result summary.
`5` when lookalikes are returned in a paid request, otherwise `0`.
Full company rows matching the seed and filters.
Number of lookalike companies returned.
Normalized seed and company filters used by the backend.
Returned company rows include the full Company Search output fields such as firmographics, funding, location, contact coverage, classification, website status, and technology columns. Lookalike rows can also include:
| Field | Type | Description |
| -------------------- | -------- | --------------------------------------------------------------------- |
| `similarity` | `number` | Vector similarity score for the matched company. |
| `source_seed_domain` | `string` | Seed domain that produced the match when multiple seeds are supplied. |
| `match_context` | `string` | Embedding text or context that helped produce the match. |
## Related endpoints
Build filtered account lists with the same output row shape.
Search contacts inside one company or a filtered company set.
## OpenAPI
````yaml post /v3/companies/lookalike
openapi: 3.1.0
info:
title: LeadMagic API
version: 1.4.34
description: >
# LeadMagic API Documentation
The LeadMagic API provides comprehensive B2B data enrichment services
including email validation, email finding, profile search, company
intelligence, and more.
## Quick Start
1. Get your API key from the [LeadMagic Dashboard](https://app.leadmagic.io)
2. Add the `X-API-Key` header to all requests
3. Start enriching your data!
## Base URL
All API requests should be made to: `https://api.leadmagic.io`
## Rate Limits
Each endpoint has specific rate limits (requests per minute). Exceeding
limits returns a `429 Too Many Requests` response.
## Credits
API calls consume credits based on the endpoint used. Check your balance
with the `/v1/credits` endpoint.
## Support
Contact us at support@leadmagic.io for assistance.
contact:
name: LeadMagic Support
email: support@leadmagic.io
url: https://leadmagic.io
termsOfService: https://leadmagic.io/legal/terms
servers:
- url: https://api.leadmagic.io
description: Production API Server
security:
- ApiKeyAuth: []
tags:
- name: Credits
description: Manage and check your credit balance
- name: Analytics
description: >-
Monitor your API usage with comprehensive analytics endpoints (FREE - no
credits consumed)
- name: People Enrichment
description: Find and validate contact information for individuals
- name: Company Data
description: Discover company information and intelligence
- name: Jobs Data
description: Search job listings and detect career changes
- name: Ads Data
description: Search advertising data across platforms
paths:
/v3/companies/lookalike:
post:
tags:
- Company Data
summary: Company Lookalike
description: >-
Find similar companies from a seed domain or description with full
company output.
operationId: company-lookalike-v3
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
company_domain:
type: string
description: Seed company domain.
example: leadmagic.io
domain:
type: string
description: Alias for company_domain.
website:
type: string
description: Seed website URL or domain.
company_name:
type: string
description: >-
Seed company name used as text intent when no domain is
supplied.
description:
type: string
description: Free-text seed description.
seed:
type: object
additionalProperties: true
company_filters:
type: object
additionalProperties: true
description: Same full company filter family as Company Search.
limit:
type: integer
minimum: 1
maximum: 2000
default: 25
offset:
type: integer
default: 0
minimum: 0
example:
company_domain: leadmagic.io
company_filters:
country_codes:
- US
employee_ranges:
- 51 to 200
- 201 to 500
has_tech_stack: true
limit: 25
responses:
'200':
description: Company lookalike results
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
message:
type: string
credits_consumed:
type: number
companies:
type: array
items:
type: object
additionalProperties: true
count:
type: integer
returned_count:
type: integer
limit_applied:
type: integer
offset:
type: integer
interpreted_search:
type: object
additionalProperties: true
metadata:
type: object
additionalProperties: true
example:
message: Lookalike companies found
credits_consumed: 5
companies:
- company_domain: example-lookalike.com
company_name: Example Lookalike
company_website: https://example-lookalike.com
company_industry_linkedin: Software
employee_range: 51 to 200
hq_country_code: US
crm_tech: Salesforce
total_contacts: 50
similarity: 0.91
source_seed_domain: leadmagic.io
match_context: B2B data platform
count: 1
returned_count: 1
limit_applied: 25
offset: 0
metadata:
query_name: company_lookalike_v3
query_path: lookalike
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'429':
$ref: '#/components/responses/RateLimitExceeded'
components:
responses:
BadRequest:
description: |
Bad Request - The request was malformed or contains invalid parameters.
**Common causes:**
- Missing required fields
- Invalid field format (e.g., malformed email)
- Invalid JSON syntax
- Invalid parameter values
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ValidationError'
Unauthorized:
description: |
Unauthorized - Authentication failed.
**Common causes:**
- Missing X-API-Key header
- Invalid or expired API key
- Malformed API key
content:
application/problem+json:
schema:
oneOf:
- $ref: '#/components/schemas/MissingAuthenticationError'
- $ref: '#/components/schemas/InvalidApiKeyError'
PaymentRequired:
description: >
Payment Required - Insufficient credits for this request.
**Action required:** Add credits to your account at
https://app.leadmagic.io/billing
content:
application/problem+json:
schema:
$ref: '#/components/schemas/InsufficientCreditsError'
RateLimitExceeded:
description: |
Too Many Requests - Rate limit exceeded.
**Action required:** Check the `Retry-After` header for when to retry.
**Headers returned:**
- `Retry-After`: Seconds until you can retry
- `RateLimit-Limit`: Your limit per minute
- `RateLimit-Remaining`: Remaining requests this minute
- `RateLimit-Reset`: Seconds until limit resets
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying
RateLimit-Limit:
schema:
type: integer
description: Maximum requests per minute
RateLimit-Remaining:
schema:
type: integer
description: Remaining requests this minute
RateLimit-Reset:
schema:
type: integer
description: Seconds until limit resets
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RateLimitExceededError'
schemas:
ValidationError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/validation_error
title: Request validation failed. Check your input parameters.
status: 400
code: validation_error
param:
- email
detail: 'Email format is invalid. Expected format: user@domain.com'
action: Provide a valid email address in the 'email' field.
docs: https://leadmagic.io/docs/api-reference/errors
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
MissingAuthenticationError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/missing_authentication
title: >-
Authentication required. Provide a valid API key in the X-API-Key
header (case-insensitive).
status: 401
code: missing_authentication
docs: https://leadmagic.io/docs/api-reference/authentication
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
InvalidApiKeyError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/invalid_api_key
title: Invalid API key. The key does not exist or is incorrect.
status: 401
code: invalid_api_key
docs: https://leadmagic.io/docs/api-reference/authentication
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
InsufficientCreditsError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/insufficient_credits
title: 'Insufficient credits: need 5, have 2.50. Add credits to continue.'
status: 402
code: insufficient_credits
detail: >-
This request requires 5 credit(s) but your account only has 2.50
credits remaining.
action: >-
Add credits to your account at https://app.leadmagic.io/billing or
contact support@leadmagic.io for enterprise plans.
docs: https://leadmagic.io/docs/api-reference/credits
context:
credits_required: 5
credits_available: 2.5
credits_needed: 2.5
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
RateLimitExceededError:
allOf:
- $ref: '#/components/schemas/ErrorResponse'
example:
success: false
errors:
- type: https://api.leadmagic.io/errors/rate_limit_exceeded
title: >-
Rate limit exceeded: 300 requests per 1 minute. Wait and try
again.
status: 429
code: rate_limit_exceeded
detail: >-
You have exceeded the maximum allowed request rate. Please wait
before making additional requests.
action: >-
Wait 42 seconds before retrying. Consider implementing exponential
backoff.
docs: https://leadmagic.io/docs/api-reference/rate-limits
context:
limit: 300
window: 1 minute
remaining: 0
reset_at: 1706745642
retry_after_seconds: 42
meta:
request_id: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp: '2024-02-01T12:00:00.000Z'
ErrorResponse:
type: object
description: RFC 9457 Problem Details error response
required:
- success
- errors
properties:
success:
type: boolean
example: false
description: Always false for error responses
errors:
type: array
description: Array of error details (typically one, but can be multiple)
items:
$ref: '#/components/schemas/ErrorDetail'
meta:
$ref: '#/components/schemas/ResponseMeta'
ErrorDetail:
type: object
description: RFC 9457 compliant error detail
required:
- type
- title
- status
properties:
type:
type: string
format: uri
description: RFC 9457 - URI reference identifying the error type
example: https://api.leadmagic.io/errors/validation_error
title:
type: string
description: RFC 9457 - Short human-readable summary
example: Request validation failed. Check your input parameters.
status:
type: integer
description: RFC 9457 - HTTP status code
example: 400
detail:
type: string
description: RFC 9457 - Human-readable explanation specific to this occurrence
example: The email field is required but was not provided.
instance:
type: string
format: uri
description: RFC 9457 - URI reference for this specific occurrence
example: /v1/people/email-validation#req_abc123
code:
type: string
description: Machine-readable error code for programmatic handling
example: validation_error
param:
type: array
description: Parameters that caused the error
items:
type: string
example:
- email
action:
type: string
description: Suggested action to resolve the error
example: Provide a valid email address in the 'email' field.
docs:
type: string
format: uri
description: Link to relevant documentation
example: https://leadmagic.io/docs/api-reference/errors
context:
type: object
description: Additional context specific to this error type
additionalProperties: true
ResponseMeta:
type: object
description: Metadata included in all responses
properties:
request_id:
type: string
format: uuid
description: Unique identifier for this request (use for debugging/support)
example: ea6e3248-f4d2-437d-bca3-20881b529129
timestamp:
type: string
format: date-time
description: ISO 8601 timestamp when the response was generated
example: '2024-02-01T12:00:00.000Z'
environment:
type: string
description: API environment (production, staging)
example: production
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: >-
Your LeadMagic API key. Header name is case-insensitive (X-API-Key,
X-API-KEY, x-api-key all work).
````