> ## 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](https://leadmagic.io/docs/v1/reference/company-search.md), plus lookalike scoring fields when available.

## Endpoint Details

> [tab] Pricing
>
> | Metric | Value |
> | - | - |
> | **Cost** | **5 credits** when lookalike companies are returned |
> | **No Results** | **FREE** |
>
> > [!TIP]
> >
> > Lookalike requests return full company rows, so you usually do not need a second lookup for each result.

> [tab] Rate Limits
>
> | 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.

**company\_domain** `string`

Seed company domain. Preferred for strongest vector lookalike matching.

**domain** `string`

Alias for `company_domain`.

**website** `string`

Seed website URL or domain. Normalized to a domain.

**seed** `object`

Optional seed object. Supports `seed.domain`, `seed.domains`, and `seed.description`.

**description** `string`

Free-text company description to embed for lookalike discovery when you do not have a seed domain.

**company\_name** `string`

Seed company name used as text intent when no domain is supplied. Domains are more precise.

**company\_filters** `object`

Same full company filter family as [Company Search](https://leadmagic.io/docs/v1/reference/company-search.md), applied after vector similarity.

**limit** `integer` (default: 25)

Number of lookalike companies to return. Maximum is `2000`.

**offset** `integer` (default: 0)

Offset for pagination.

## Response

**message** `string`

Human-readable result summary.

**credits\_consumed** `number`

`5` when lookalikes are returned in a paid request, otherwise `0`.

**companies** `object[]`

Full company rows matching the seed and filters.

**count** `integer`

Number of lookalike companies returned.

**interpreted\_search** `object`

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

> [card] [Company Search](https://leadmagic.io/docs/v1/reference/company-search.md)
>
> Build filtered account lists with the same output row shape.

> [card] [People Search](https://leadmagic.io/docs/v1/reference/people-search.md)
>
> 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).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.