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

# Search companies

> Call company_search through the Plyne API or MCP. Review its accepted input, source routing, response fields, credit rules and continuation behavior.

Find companies by industry, location, size and keywords across eligible company-data providers.

## Usage

* Common keyword searches use sources with matching keyword semantics. FullEnrich uses its native filters without a common query; those options select FullEnrich alone.
* Normalized search records retain reviewed fields outside their common schema in additional\_fields.\<provider>. Source-native data tools already expose their documented business fields directly in data.

## API

Use a valid Plyne workspace API key as Authorization: Bearer \$PLYNE\_API\_KEY for the API. Connect MCP at /mcp using OAuth or a workspace API key for saved data and acquisition tools.

```bash theme={null}
curl "$PLYNE_API_URL/v1/tools/company_search/execute" \
  -H "Authorization: Bearer $PLYNE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: REPLACE_WITH_UNIQUE_REQUEST_ID' \
  --data '{
  "query": "finance"
}'
```

Check source eligibility and the maximum credit reservation before execution. Planning makes no provider request and requires no idempotency key.

```bash theme={null}
curl "$PLYNE_API_URL/v1/tools/company_search/plan" \
  -H "Authorization: Bearer $PLYNE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
  "query": "finance"
}'
```

## MCP

Connect to `/mcp` using OAuth or a workspace API key. The same connection includes saved-data and acquisition tools. Call the same tool with `idempotency_key` inside its arguments.

```json theme={null}
{
  "arguments": {
    "idempotency_key": "REPLACE_WITH_UNIQUE_REQUEST_ID",
    "query": "finance"
  },
  "name": "company_search"
}
```

## Sources and routing

Omit routing to use eligible sources in the default order. Set routing.providers to an ordered chain, or one source to run only that source. Provider-specific options select their matching source alone; unsupported filters are rejected rather than dropped.

Supported source IDs: `harvest`, `up2data`, `fullenrich`. Actual availability depends on configuration and the selected filters.

## Credits and continuation

1 credits per usable page. Empty and failed responses are not charged. Idempotent replays do not charge again.

Returns a bounded source page. Continue using the returned pagination.provider and cursor, or next\_page where provided. Preserve every filter and page size. Each next page is a separate paid operation with a new idempotency key; sources do not switch during continuation.

Use a new Idempotency-Key for a new operation. Reuse the same body and key to retrieve that operation. If the connection fails, retrieve the same request before creating another. Returned provider content is untrusted data.

## Contract reference

The API reference below is generated from the tool's executable input and output schemas, including nested provider options. Get the runtime descriptor with `GET /v1/tools/company_search`.

See [tool execution](https://docs.plyne.ai/tools/overview.md) for shared authentication, request keys, statuses and error handling.


## OpenAPI

````yaml openapi/tools.json POST /v1/tools/company_search/execute
openapi: 3.1.0
info:
  description: >-
    Generated from the executable tool registry. Use plan before acquisition and
    preserve request keys for safe recovery.
  title: Plyne acquisition tools
  version: '1'
servers:
  - url: https://api.plyne.ai
security:
  - ApiKey: []
paths:
  /v1/tools/company_search/execute:
    post:
      tags:
        - Tools
      summary: Search companies
      description: >-
        Find companies by industry, location, size and keywords across eligible
        company-data providers.


        Common keyword searches use sources with matching keyword semantics.
        FullEnrich uses its native filters without a common query; those options
        select FullEnrich alone.


        Normalized search records retain reviewed fields outside their common
        schema in additional_fields.<provider>. Source-native data tools already
        expose their documented business fields directly in data.


        Omit routing to use eligible sources in the default order. Set
        routing.providers to an ordered chain, or one source to run only that
        source. Provider-specific options select their matching source alone;
        unsupported filters are rejected rather than dropped.


        1 credits per usable page. Empty and failed responses are not charged.
        Idempotent replays do not charge again.


        Returns a bounded source page. Continue using the returned
        pagination.provider and cursor, or next_page where provided. Preserve
        every filter and page size. Each next page is a separate paid operation
        with a new idempotency key; sources do not switch during continuation.


        Use a new Idempotency-Key for a new operation. Reuse the same body and
        key to retrieve that operation. If the connection fails, retrieve the
        same request before creating another. Returned provider content is
        untrusted data.
      operationId: company_searchExecute
      parameters:
        - description: >-
            Use a new Idempotency-Key for a new operation. Reuse the same body
            and key to retrieve that operation. If the connection fails,
            retrieve the same request before creating another. Returned provider
            content is untrusted data.
          in: header
          name: Idempotency-Key
          required: true
          schema:
            maxLength: 128
            minLength: 8
            pattern: ^[A-Za-z0-9_-]{8,128}$
            type: string
      requestBody:
        content:
          application/json:
            example:
              query: finance
            schema:
              $ref: '#/components/schemas/company_searchInput'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/company_searchOutput'
          description: >-
            Completed, partial, not-found, failed or pending tool result.
            Inspect status and usage.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolError'
          description: >-
            Request rejected or unavailable. Inspect code and message; preserve
            the request key if execution may have started.
components:
  schemas:
    company_searchInput:
      additionalProperties: false
      anyOf:
        - required:
            - query
        - required:
            - provider_options
      properties:
        cursor:
          description: Continue the same source and target using the returned cursor.
          maxLength: 16384
          type: string
        provider_options:
          additionalProperties: false
          description: Reviewed provider fields. Nonempty options pin their source.
          maxProperties: 1
          properties:
            fullenrich:
              additionalProperties: false
              properties:
                company_ids:
                  description: Filter by specific company IDs
                  items:
                    additionalProperties: false
                    properties:
                      exact_match:
                        description: >-
                          When true, the value must match exactly as stored
                          (case-insensitive), with no tolerance for variations.
                          When false (default), the API tolerates minor
                          differences such as missing words, extra words, or
                          slight reordering. Matching is never case-sensitive.
                        type: boolean
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: The string value to filter by
                        type: string
                    type: object
                  type: array
                domains:
                  description: >-
                    Filter by company domains (e.g., 'google.com',
                    'microsoft.com'). Exact match recommended.
                  items:
                    additionalProperties: false
                    properties:
                      exact_match:
                        description: >-
                          When true, the value must match exactly as stored
                          (case-insensitive), with no tolerance for variations.
                          When false (default), the API tolerates minor
                          differences such as missing words, extra words, or
                          slight reordering. Matching is never case-sensitive.
                        type: boolean
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: The string value to filter by
                        type: string
                    type: object
                  type: array
                founded_years:
                  description: >-
                    Filter by founding years. Useful for targeting startups
                    (recent years) or established companies.
                  items:
                    additionalProperties: false
                    properties:
                      exclude:
                        description: If true, excludes companies founded in this range
                        type: boolean
                      max:
                        description: Maximum founding year (inclusive)
                        type: integer
                      min:
                        description: Minimum founding year (inclusive)
                        type: integer
                    type: object
                  type: array
                headcounts:
                  description: >-
                    Filter by company headcounts (number of employees). Use
                    ranges to target specific company sizes (e.g., startups:
                    1-50, mid-size: 50-500, enterprise: 1000+).
                  items:
                    additionalProperties: false
                    properties:
                      exclude:
                        description: If true, excludes companies in this range
                        type: boolean
                      max:
                        description: Maximum number of employees (inclusive)
                        type: integer
                      min:
                        description: Minimum number of employees (inclusive)
                        type: integer
                    type: object
                  type: array
                headquarters_locations:
                  description: >-
                    Filter by headquarters locations (city names, regions, or
                    countries)
                  items:
                    additionalProperties: false
                    properties:
                      exact_match:
                        description: >-
                          When true, the value must match exactly as stored
                          (case-insensitive), with no tolerance for variations.
                          When false (default), the API tolerates minor
                          differences such as missing words, extra words, or
                          slight reordering. Matching is never case-sensitive.
                        type: boolean
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: The string value to filter by
                        type: string
                    type: object
                  type: array
                industries:
                  description: >-
                    Filter by company industries (e.g., 'Software Development',
                    'Computer Hardware Manufacturing', 'Housing and Community
                    Development', 'Warehousing', 'Financial Services'). See
                    [Industries](/api/v2/general/enums#company-industry) for the
                    full list.
                  items:
                    additionalProperties: false
                    properties:
                      exact_match:
                        description: >-
                          When true, the value must match exactly as stored
                          (case-insensitive), with no tolerance for variations.
                          When false (default), the API tolerates minor
                          differences such as missing words, extra words, or
                          slight reordering. Matching is never case-sensitive.
                        type: boolean
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: The string value to filter by
                        type: string
                    type: object
                  type: array
                  x-plyne-catalog:
                    helper: search_catalog
                    id: fullenrich.industries
                keywords:
                  description: Filter by description of company
                  items:
                    additionalProperties: false
                    properties:
                      exact_match:
                        description: >-
                          When true, the value must match exactly as stored
                          (case-insensitive), with no tolerance for variations.
                          When false (default), the API tolerates minor
                          differences such as missing words, extra words, or
                          slight reordering. Matching is never case-sensitive.
                        type: boolean
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: The string value to filter by
                        type: string
                    type: object
                  type: array
                names:
                  description: >-
                    Filter by company names. Use exact_match for precise company
                    name matching.
                  items:
                    additionalProperties: false
                    properties:
                      exact_match:
                        description: >-
                          When true, the value must match exactly as stored
                          (case-insensitive), with no tolerance for variations.
                          When false (default), the API tolerates minor
                          differences such as missing words, extra words, or
                          slight reordering. Matching is never case-sensitive.
                        type: boolean
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: The string value to filter by
                        type: string
                    type: object
                  type: array
                professional_network_ids:
                  description: Filter by professional network IDs.
                  items:
                    additionalProperties: false
                    properties:
                      exact_match:
                        description: >-
                          When true, the exact term must appear within the
                          value, but can still be part of a longer string. When
                          false (default), matching is flexible and tolerates
                          slight variations such as missing or extra words.
                          Matching is never case-sensitive.
                        type: boolean
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: The integer value to filter by
                        type: integer
                    type: object
                  type: array
                professional_network_urls:
                  description: Filter by professional network URLs.
                  items:
                    additionalProperties: false
                    properties:
                      exact_match:
                        description: >-
                          When true, the value must match exactly as stored
                          (case-insensitive), with no tolerance for variations.
                          When false (default), the API tolerates minor
                          differences such as missing words, extra words, or
                          slight reordering. Matching is never case-sensitive.
                        type: boolean
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: The string value to filter by
                        type: string
                    type: object
                  type: array
                revenue_ranges:
                  description: >-
                    Filter by company annual revenue brackets. See [Company
                    Revenue](/api/v2/general/enums#company-revenue) for the full
                    list of accepted values.
                  items:
                    additionalProperties: false
                    properties:
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: >-
                          The revenue bracket to filter by. Must be one of the
                          accepted values (e.g., '<$1M', '$10M-$50M', '>$1B').
                        enum:
                          - <$1M
                          - $1M-$10M
                          - $10M-$50M
                          - $50M-$100M
                          - $100M-$500M
                          - $500M-$1B
                          - '>$1B'
                        type: string
                    type: object
                  type: array
                specialties:
                  description: Filter by specialties of company
                  items:
                    additionalProperties: false
                    properties:
                      exact_match:
                        description: >-
                          When true, the value must match exactly as stored
                          (case-insensitive), with no tolerance for variations.
                          When false (default), the API tolerates minor
                          differences such as missing words, extra words, or
                          slight reordering. Matching is never case-sensitive.
                        type: boolean
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: The string value to filter by
                        type: string
                    type: object
                  type: array
                technologies:
                  description: >-
                    Filter by technologies used by the company (e.g., 'Notion',
                    'Fullenrich', 'AWS').
                  items:
                    additionalProperties: false
                    properties:
                      exact_match:
                        description: >-
                          When true, the value must match exactly as stored
                          (case-insensitive), with no tolerance for variations.
                          When false (default), the API tolerates minor
                          differences such as missing words, extra words, or
                          slight reordering. Matching is never case-sensitive.
                        type: boolean
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: The string value to filter by
                        type: string
                    type: object
                  type: array
                types:
                  description: >-
                    Filter by company types (e.g., 'Public Company', 'Privately
                    Held', 'Nonprofit', 'Self-Employed', 'Partnership',
                    'Educational', 'Government Agency'). See [Company
                    Types](/api/v2/general/enums#company-type) for the full
                    list.
                  items:
                    additionalProperties: false
                    properties:
                      exact_match:
                        description: >-
                          When true, the value must match exactly as stored
                          (case-insensitive), with no tolerance for variations.
                          When false (default), the API tolerates minor
                          differences such as missing words, extra words, or
                          slight reordering. Matching is never case-sensitive.
                        type: boolean
                      exclude:
                        description: >-
                          If true, excludes results matching this value. If
                          false or omitted (default), includes only matching
                          results.
                        type: boolean
                      value:
                        description: The string value to filter by
                        type: string
                    type: object
                  type: array
              type: object
            harvest:
              additionalProperties: false
              properties:
                companySize:
                  type: string
                geoId:
                  type: string
                industryId:
                  type: string
                location:
                  type: string
              type: object
            up2data:
              additionalProperties: false
              properties:
                filters:
                  additionalProperties: false
                  properties:
                    company_sizes:
                      items:
                        type: string
                      type: array
                    industry_ids:
                      items:
                        description: FacetId
                        type:
                          - string
                          - object
                      type: array
                    location_ids:
                      items:
                        description: FacetId
                        type:
                          - string
                          - object
                      type: array
                  type: object
                max_results:
                  maximum: 100
                  minimum: 1
                  type: integer
              required:
                - filters
              type: object
          type: object
        query:
          description: >-
            Search keywords. Use provider_options for advanced source filters;
            source-specific options pin that source.
          maxLength: 2048
          minLength: 1
          type: string
        routing:
          additionalProperties: false
          dependentRequired:
            fallback_on:
              - providers
          description: >-
            Optional source chain. One source runs alone; multiple sources are
            tried in order. All selected sources must support the request.
            Provider options require a matching one-source chain.
          properties:
            fallback_on:
              description: >-
                When to try the next source. Defaults to error and empty; has no
                effect for one source.
              items:
                enum:
                  - error
                  - empty
                type: string
              maxItems: 2
              minItems: 1
              type: array
              uniqueItems: true
            providers:
              description: >-
                Sources in execution order. One entry uses only that source.
                Omit to use the default chain.
              items:
                enum:
                  - harvest
                  - up2data
                  - fullenrich
                type: string
              maxItems: 3
              minItems: 1
              type: array
              uniqueItems: true
          type: object
      type: object
    company_searchOutput:
      additionalProperties: false
      properties:
        data:
          items:
            additionalProperties: false
            properties:
              additional_fields:
                additionalProperties: false
                properties:
                  fullenrich:
                    additionalProperties: false
                    properties:
                      company_type:
                        description: >-
                          Type of company (e.g., 'Public Company', 'Privately
                          Held', 'Nonprofit', 'Self-Employed', 'Partnership',
                          'Educational', 'Government Agency')
                        type: string
                      description:
                        description: Company description
                        type: string
                      domain:
                        description: Company domain
                        type: string
                      headcount:
                        description: >-
                          Exact number of employees. May return 0 even when
                          headcount_range is available.
                        type: integer
                      headcount_range:
                        description: >-
                          Employee count range (e.g., '1-10', '11-50', '51-200',
                          '201-500', '501-1000', '1001-5000', '5001-10000',
                          '10001+')
                        type: string
                      id:
                        description: Unique company identifier
                        type: string
                      industry:
                        additionalProperties: false
                        description: Company industry information
                        properties:
                          main_industry:
                            description: >-
                              Primary industry category (e.g., 'Software
                              Development', 'Computer Hardware Manufacturing',
                              'Financial Services', 'Healthcare', 'Retail')
                            type: string
                        type: object
                      locations:
                        additionalProperties: false
                        description: Company location information
                        properties:
                          headquarters:
                            additionalProperties: false
                            description: >-
                              Main headquarters address with structured location
                              fields. Can be an empty object when no
                              headquarters data is available.
                            properties:
                              city:
                                description: City name
                                type: string
                              country:
                                description: Country name
                                type: string
                              country_code:
                                description: ISO country code
                                type: string
                              line1:
                                description: Address line 1 (street address)
                                type: string
                              line2:
                                description: >-
                                  Address line 2 (full location string including
                                  city, region, postal code, and country code)
                                type: string
                              region:
                                description: State or region
                                type: string
                            type: object
                          offices:
                            description: >-
                              Additional office locations. Only contains raw
                              address lines (line1, line2) without structured
                              city/region/country fields. Can be null or an
                              empty array.
                            items:
                              additionalProperties: false
                              description: >-
                                Office address. Unlike headquarters, office
                                addresses only contain raw address lines without
                                parsed location fields.
                              properties:
                                line1:
                                  description: Street address
                                  type: string
                                line2:
                                  description: >-
                                    Full location string (city, region, postal
                                    code, country code)
                                  type: string
                              type: object
                            type:
                              - array
                              - 'null'
                        type: object
                      logo_url:
                        description: >-
                          URL of the company logo hosted by FullEnrich, built
                          from the company's professional network handle. Empty
                          when the handle is unknown.
                        type: string
                      name:
                        description: Company name
                        type: string
                      revenue:
                        additionalProperties: false
                        description: >-
                          Estimated annual revenue of the company. Omitted when
                          unknown.
                        properties:
                          confidence:
                            description: >-
                              Confidence level of the revenue estimate. Omitted
                              when unknown.
                            enum:
                              - HIGH
                              - MEDIUM
                              - LOW
                            type: string
                          range:
                            description: >-
                              Annual revenue bracket. See [Company
                              Revenue](/api/v2/general/enums#company-revenue)
                              for the full list of possible values.
                            enum:
                              - <$1M
                              - $1M-$10M
                              - $10M-$50M
                              - $50M-$100M
                              - $100M-$500M
                              - $500M-$1B
                              - '>$1B'
                            type: string
                        type: object
                      social_profiles:
                        additionalProperties: false
                        description: Company's social media profiles
                        properties:
                          professional_network:
                            additionalProperties: false
                            description: Professional network profile information
                            properties:
                              connection_count:
                                description: Number of professional network followers
                                type: integer
                              handle:
                                description: Professional network profile handle/username
                                type: string
                              id:
                                description: Professional network profile ID
                                type: integer
                              url:
                                description: Full professional network profile URL
                                type: string
                            type: object
                        type: object
                      specialties:
                        description: Specialties associated with the company
                        items:
                          type: string
                        type: array
                      technologies:
                        description: Technologies used by the company
                        items:
                          additionalProperties: false
                          properties:
                            logo_url:
                              description: URL of the technology logo
                              type: string
                            name:
                              description: Technology name
                              type: string
                          type: object
                        type: array
                      website:
                        description: >-
                          Company website URL as declared by the company. May
                          differ from `domain` (can include a subdomain, a path
                          or tracking parameters). Omitted when not available.
                        type: string
                      year_founded:
                        description: Year the company was founded. Returns 0 when unknown.
                        type: integer
                    type: object
                  harvest:
                    additionalProperties: false
                    properties:
                      followers:
                        type: string
                      id:
                        type: string
                      industries:
                        type: string
                      linkedinUrl:
                        type: string
                      location:
                        additionalProperties: false
                        properties:
                          linkedinText:
                            type: string
                        type: object
                      logo:
                        type: string
                      name:
                        type: string
                      summary:
                        type: string
                      universalName:
                        type: string
                    type: object
                  up2data:
                    additionalProperties: false
                    properties:
                      industry: {}
                      linkedin_id: {}
                      name: {}
                      scraped_at: {}
                      url: {}
                    type: object
                type: object
              headline:
                description: Public professional headline.
                type: string
              id:
                description: Source identity.
                type: string
              industry:
                description: Industry when available.
                type: string
              kind:
                const: company
              name:
                description: Display name.
                type: string
              url:
                description: LinkedIn URL.
                type: string
            type: object
          type:
            - array
            - 'null'
        error:
          additionalProperties: false
          properties:
            code:
              type: string
            message:
              type: string
            retryable:
              type: boolean
          required:
            - code
            - message
            - retryable
          type:
            - object
            - 'null'
        fulfillment:
          properties:
            field_sources:
              additionalProperties:
                items:
                  properties:
                    observation_id:
                      type: string
                    observed_at:
                      properties: {}
                      type: object
                    provider:
                      type: string
                    url:
                      type: string
                  type: object
                type: array
              type: object
            missing_fields:
              items:
                type: string
              type: array
            satisfied:
              type: boolean
          type: object
        id:
          type: string
        pagination:
          properties:
            cursor:
              type: string
            has_more:
              type:
                - boolean
                - 'null'
            limit:
              type: integer
            provider:
              enum:
                - harvest
                - up2data
                - fullenrich
            returned:
              type: integer
          type: object
        routing:
          additionalProperties: false
          properties:
            attempts:
              items:
                additionalProperties: false
                properties:
                  outcome:
                    enum:
                      - success
                      - partial
                      - pending
                      - error
                      - empty
                    type: string
                  provider:
                    type: string
                  requests:
                    minimum: 0
                    type: integer
                required:
                  - provider
                  - outcome
                  - requests
                type: object
              type: array
            mode:
              enum:
                - auto
                - single
                - fallback
              type: string
            selected_provider:
              type: string
          required:
            - mode
          type: object
        sources:
          items:
            additionalProperties: false
            properties:
              observation_id:
                type: string
              observed_at:
                format: date-time
                type: string
              provider:
                type: string
              url:
                type: string
            required:
              - provider
            type: object
          type: array
        status:
          enum:
            - completed
            - partial
            - not_found
            - failed
            - pending
          type: string
        tool:
          const: company_search
          type: string
        usage:
          additionalProperties: false
          properties:
            credit_units:
              minimum: 0
              type: integer
            credits:
              type: string
            unit:
              const: page
          required:
            - credit_units
            - credits
            - unit
          type:
            - object
            - 'null'
        version:
          const: '1'
          type: string
        warnings:
          items:
            additionalProperties: false
            properties:
              code:
                type: string
              message:
                type: string
            required:
              - code
              - message
            type: object
          type: array
      required:
        - id
        - tool
        - version
        - status
        - data
        - sources
        - usage
        - error
      type: object
    ToolError:
      properties:
        code:
          type: string
        message:
          type: string
      required:
        - code
        - message
      type: object
  securitySchemes:
    ApiKey:
      scheme: bearer
      type: http

````

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