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

# Search Companies via Query

> 

Search and enrich companies using natural language queries.

This endpoint allows you to search for companies using natural language (e.g., "SaaS companies in London with 50-200 employees") and optionally enrich them with insights, decision makers, or custom queries.

Results are delivered to the provided `webhookUrl`.



## OpenAPI

````yaml /api-reference/combined.json post /v1/companies/search
openapi: 3.1.0
info:
  title: Precept API
  description: >-
    Precept API provides powerful, programmatic access to our AI-driven B2B
    account research, company enrichment, and verified contact data
    capabilities. Use these endpoints to discover high-intent companies, map
    decision-makers, and run personalized enrichment pipelines directly
    integrating with your CRM, spreadsheets, or automated workflows like Make
    and n8n.
  version: 1.0.0
servers:
  - url: https://api.preceptai.co.uk
security:
  - bearerAuth: []
paths:
  /v1/companies/search:
    post:
      tags:
        - Companies
      summary: Search Companies via Query
      description: >-


        Search and enrich companies using natural language queries.


        This endpoint allows you to search for companies using natural language
        (e.g., "SaaS companies in London with 50-200 employees") and optionally
        enrich them with insights, decision makers, or custom queries.


        Results are delivered to the provided `webhookUrl`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompanySearchRequest'
            examples:
              default:
                summary: Search for companies and find decision makers.
                value:
                  query: SaaS companies in the UK with 50-200 employees
                  webhookUrl: https://your-site.com/webhook
                  enrichments:
                    type: decision_makers
                    departments:
                      - marketing
                    jobTitles:
                      - Head of Marketing
                    includeContactDetails: true
                    decisionMakersLimit: 5
      responses:
        '202':
          description: Request accepted. The search and enrichment are in progress.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: >-
                      Company search job successfully created and is being
                      processed.
                  enrichment_id:
                    type: string
                    format: uuid
        '400':
          description: Invalid input.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
        '402':
          description: Insufficient credits.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
components:
  schemas:
    CompanySearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: Natural language query to search for companies.
        webhookUrl:
          type: string
          format: uri
          description: >-
            Optional. Your webhook URL to receive the result of the company
            search operations. If not provided, you can poll the GET
            /v1/jobs/{jobId} endpoint.
        limit:
          type: integer
          maximum: 1000
          description: Maximum number of companies to return (up to 1000).
        name:
          type: string
          description: A readable name for your enrichment job.
        enrichments:
          type: object
          description: >-
            Optional enrichments to perform for each discovered company. See the
            [Company Enrichments](/essentials/enrichments) guide for detailed
            descriptions and example responses for each type.
          properties:
            type:
              type: string
              description: >-
                The type of structured enrichment to perform. Enrichment types
                are broken down into three categories:


                | Category | Type | Explanation |

                | --- | --- | --- |

                | **Company-level** | `technology_stack` | Identifies the
                software, tools, and technologies used by the company. |

                | | `revenue` | Retrieves the estimated annual revenue of the
                company. |

                | | `recent_funding` | Provides details about the company's most
                recent funding rounds and investors. |

                | **Department-level** (Requires `departments` and/or
                `jobTitles`)* | `employee_count` | Returns the total headcount
                within specified departments or job titles. |

                | | `employee_count_change` | Shows the growth or decline in
                employee headcount over time for specific roles. |

                | | `department_ratio` | Calculates the percentage of the
                company's total workforce that belongs to a specific department.
                |

                | | `job_posting_insights` | Analyzes active job postings and
                hiring trends for specified departments. |

                | **Lead-level** | `decision_makers` | Finds specific people
                based on the provided `departments` and/or `jobTitles`. The
                people are searched in the order of seniority, most senior
                employees are returned first. |

                | | `all_employees` | Fetches the company's entire employee
                directory. |
              enum:
                - decision_makers
                - all_employees
                - employee_count
                - job_posting_insights
                - department_ratio
                - employee_count_change
                - technology_stack
                - revenue
                - recent_funding
            departments:
              type: array
              items:
                type: string
            jobTitles:
              type: array
              items:
                type: string
            country:
              type: array
              items:
                type: string
            includeContactDetails:
              type: boolean
            decisionMakersLimit:
              type: integer
            limitType:
              type: string
              enum:
                - per_role
                - overall
        queries:
          type: array
          items:
            type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````