> ## Documentation Index
> Fetch the complete documentation index at: https://docs.extruct.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> Find similar companies with filters in a JSON body (POST variant).

# Find Similar Companies

## Overview

The `POST` variant of [Lookalike Search](/api-reference/lookalike-search) takes `filters` as a native JSON object in the body instead of a URL-encoded string. The reference company stays in the path. Use it when an `exclude.domains` list is too large to fit a `GET` URL.

## Example request

```bash theme={null}
export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"

curl -X POST "https://api.extruct.ai/v1/companies/stripe.com/similar" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {"exclude": {"domains": ["stripe.com", "adyen.com"]}},
    "pagination": {"offset": 0, "limit": 20}
  }'
```

## Key parameters

* `company_identifier` (path, required): Reference company UUID or domain.
* `filters` (optional): SearchFilters as a JSON object. See [Search Filters Reference](/api-guides/search/search-filters-reference).
* `pagination` (optional): `{ "offset": <int>, "limit": <int> }`; `limit` up to `250` per request.

## Endpoint behavior

* Identical ranking and results to the `GET` lookalike endpoint; only the transport differs.
* The reference company is excluded from its own results; `exclude.domains` is additive.
* A single request returns at most `250` results. Page with `pagination.offset` to read deeper.

## Success signal

Returns `results`, the `reference_company`, and request metadata, the same shape as the `GET` endpoint.

## Common errors

### `401 Unauthorized`

Check that your header is `Authorization: Bearer ${EXTRUCT_API_TOKEN}`.

### `404 Not Found`

The reference company was not found in the index. Verify the UUID or domain.

### `422 Unprocessable Entity`

An invalid domain in `exclude.domains`, more than `1000` domains after de-duplication, or a malformed body.

## Related endpoints

* [Lookalike Search Endpoint (GET)](/api-reference/lookalike-search)
* [Search Endpoint (POST)](/api-reference/search-post)

## Related guides

* [Search Filters Reference](/api-guides/search/search-filters-reference)
* [Lookalike Search](/api-guides/search/lookalike-search)


## OpenAPI

````yaml POST /v1/companies/{company_identifier}/similar
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security: []
paths:
  /v1/companies/{company_identifier}/similar:
    post:
      tags:
        - search
      summary: Find Similar Companies
      description: >-
        POST variant of lookalike search. Send `filters` as a JSON object (not a
        string). Use this when an `exclude.domains` list is too large for a GET
        URL.
      operationId: >-
        find_similar_companies_post_v1_companies__company_identifier__similar_post
      parameters:
        - name: company_identifier
          in: path
          required: true
          schema:
            type: string
            title: Company Identifier
          description: Reference company UUID or domain.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanyLookalikePostInput'
              examples:
                - filters:
                    exclude:
                      domains:
                        - stripe.com
                        - adyen.com
                  pagination:
                    offset: 0
                    limit: 20
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompanyLookalikeResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    CompanyLookalikePostInput:
      type: object
      title: CompanyLookalikePostInput
      description: >-
        Request body for POST lookalike search. The reference company is in the
        path.
      additionalProperties: false
      properties:
        filters:
          anyOf:
            - $ref: '#/components/schemas/SearchFilters'
            - type: 'null'
          description: Structured filters (same contract as the GET filters string).
        pagination:
          anyOf:
            - $ref: '#/components/schemas/Pagination'
            - type: 'null'
          description: Offset/limit pagination.
    CompanyLookalikeResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/CompanySearchResult'
          type: array
          title: Results
          description: Search results
        request:
          $ref: '#/components/schemas/LookalikeRequestInfo'
          description: Request parameters echo
        reference_company:
          anyOf:
            - $ref: '#/components/schemas/CompanySearchResult'
            - type: 'null'
          description: Reference company for lookalike searches
      type: object
      required:
        - results
        - request
      title: CompanyLookalikeResponse
      description: Lookalike search response wrapper.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SearchFilters:
      type: object
      title: SearchFilters
      description: Structured filters for search and lookalike endpoints.
      additionalProperties: false
      properties:
        include:
          $ref: '#/components/schemas/SearchFiltersInclude'
        exclude:
          $ref: '#/components/schemas/SearchFiltersExclude'
        range:
          $ref: '#/components/schemas/SearchFiltersRange'
    Pagination:
      type: object
      title: Pagination
      additionalProperties: false
      properties:
        offset:
          anyOf:
            - type: integer
            - type: 'null'
          description: Number of results to skip.
        limit:
          anyOf:
            - type: integer
            - type: 'null'
          description: Maximum results to return in one response (max 250).
    CompanySearchResult:
      properties:
        id:
          type: string
          title: Id
          description: Company ID
        domain:
          type: string
          title: Domain
          description: Company domain
        name:
          type: string
          title: Name
          description: Company name
        short_description:
          anyOf:
            - type: string
            - type: 'null'
          description: Brief company description
        full_description:
          anyOf:
            - type: string
            - type: 'null'
          description: Detailed company description
        products_services:
          anyOf:
            - type: string
            - type: 'null'
          description: Products and services offered
        use_cases:
          anyOf:
            - type: string
            - type: 'null'
          description: Use cases for products/services
        target_audience:
          anyOf:
            - type: string
            - type: 'null'
          description: Target customer audience
        other_considerations:
          anyOf:
            - type: string
            - type: 'null'
          description: Additional considerations
        founding_year:
          anyOf:
            - type: integer
            - type: 'null'
          description: Year company was founded
        employee_count:
          anyOf:
            - type: string
            - type: 'null'
          description: Employee count range
        hq_country:
          anyOf:
            - type: string
            - type: 'null'
          description: Headquarters country
        hq_state_province:
          anyOf:
            - type: string
            - type: 'null'
          description: Headquarters state/province
        hq_city:
          anyOf:
            - type: string
            - type: 'null'
          description: Headquarters city
        hq_full_address:
          anyOf:
            - type: string
            - type: 'null'
          description: Full headquarters address
        social_profiles:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          description: Social media profiles
        website_authority:
          anyOf:
            - $ref: '#/components/schemas/WebsiteAuthority'
            - type: 'null'
          description: Website authority metrics
        relevance_score:
          anyOf:
            - type: number
            - type: 'null'
          description: Relevance score (0-1)
      type: object
      required:
        - id
        - domain
        - name
      title: CompanySearchResult
      description: Individual company search result.
    LookalikeRequestInfo:
      properties:
        query:
          anyOf:
            - type: string
            - type: 'null'
          description: Search query text
        offset:
          type: integer
          title: Offset
          description: Result offset
        limit:
          type: integer
          title: Limit
          description: Results limit
        filters:
          anyOf:
            - $ref: '#/components/schemas/SearchFilters'
            - type: 'null'
          description: Applied filters (SearchFilters object).
        reference_company_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Reference company ID for lookalike search
      type: object
      required:
        - offset
        - limit
      title: LookalikeRequestInfo
      description: Lookalike search request parameters.
    ValidationError:
      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
    SearchFiltersInclude:
      type: object
      title: SearchFiltersInclude
      description: Include companies that match these values.
      additionalProperties: false
      properties:
        size:
          type: array
          items:
            $ref: '#/components/schemas/CompanySize'
          description: Employee size buckets to include.
        country:
          type: array
          items:
            type: string
          description: Headquarters countries to include.
        city:
          type: array
          items:
            type: string
          description: Headquarters cities to include.
    SearchFiltersExclude:
      type: object
      title: SearchFiltersExclude
      description: Exclude companies that match these values.
      additionalProperties: false
      properties:
        size:
          type: array
          items:
            $ref: '#/components/schemas/CompanySize'
          description: Employee size buckets to exclude.
        country:
          type: array
          items:
            type: string
          description: Headquarters countries to exclude.
        city:
          type: array
          items:
            type: string
          description: Headquarters cities to exclude.
        domains:
          type: array
          items:
            type: string
          description: >-
            Company domains or URLs to exclude from results. Normalized to the
            registered domain server-side; alias-aware; max 1000.
    SearchFiltersRange:
      type: object
      title: SearchFiltersRange
      description: Numeric range constraints.
      additionalProperties: false
      properties:
        founded:
          $ref: '#/components/schemas/FoundedYearRange'
          description: Filter companies by founding year range.
    WebsiteAuthority:
      properties:
        score:
          type: integer
          title: Score
          description: Authority score (0-100)
        tier:
          type: string
          title: Tier
          description: Authority tier classification
        tier_label:
          type: string
          title: Tier Label
          description: Human-readable tier label
      type: object
      required:
        - score
        - tier
        - tier_label
      title: WebsiteAuthority
      description: Website authority scoring details.
    CompanySize:
      type: string
      enum:
        - 1-10
        - 11-50
        - 51-200
        - 201-500
        - 501-1000
        - 1001-5000
        - 5001-10000
        - 10001+
      title: CompanySize
      description: Employee headcount buckets using LinkedIn-style ranges.
    FoundedYearRange:
      type: object
      title: FoundedYearRange
      description: Inclusive range bounds for founding year.
      additionalProperties: false
      properties:
        min:
          type: integer
          description: Minimum founding year (inclusive).
        max:
          type: integer
          description: Maximum founding year (inclusive).
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````