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

# Search Companies by Firmographics and Tech Stack

> Use The Hog's company search to find target accounts by industry, employee count, revenue, technology, and buying signals like hiring and funding.

The company search endpoint is the starting point for building targeted account lists. You send a POST request with a natural-language query and optional structured filters, then poll the returned operation for ranked company results. The `query` field is required.

## Endpoint

```text theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST https://developer.thehog.ai/api/v1/companies/search
```

## Request fields

<CardGroup cols={2}>
  <Card title="Text & Identity" icon="magnifying-glass">
    `query` — free-text search on company name or domain (up to 256 characters)

    `filters.company.domains` — exact domain filters (e.g. `["acme.com"]`)
  </Card>

  <Card title="Firmographics" icon="building">
    `filters.industries`, `filters.locations`, `filters.employeeCount.min/max`
  </Card>

  <Card title="Technographics" icon="microchip">
    Include tools in `query`, or use `filters.signals` for known buying-signal categories.
  </Card>

  <Card title="Signals" icon="signal">
    `filters.signals` — short signal labels such as `["hiring", "funding"]`
  </Card>
</CardGroup>

### Pagination

| Field   | Default | Maximum | Notes            |
| ------- | ------- | ------- | ---------------- |
| `limit` | `25`    | `100`   | Results per page |

## Examples

<CodeGroup>
  ```bash Simple text search theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://developer.thehog.ai/api/v1/companies/search \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Acme",
      "limit": 10
    }'
  ```

  ```bash Firmographic + technographic + signal filters theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://developer.thehog.ai/api/v1/companies/search \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Software companies using Salesforce and HubSpot",
      "filters": {
        "industries": ["Software"],
        "locations": ["United States"],
        "employeeCount": { "min": 50, "max": 500 },
        "signals": ["hiring"]
      },
      "limit": 25
    }'
  ```

  ```bash Signal-focused search theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://developer.thehog.ai/api/v1/companies/search \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "FinTech companies hiring revenue teams",
      "filters": {
        "industries": ["FinTech"],
        "signals": ["hiring"]
      },
      "limit": 20
    }'
  ```
</CodeGroup>

## Response

A successful submission returns HTTP `202` with an operation ID and poll URL. Poll `GET /api/operations/:id` until the operation succeeds.

<CodeGroup>
  ```json Accepted response theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "id": "op_01hxyz",
    "operationId": "op_01hxyz",
    "status": "queued",
    "pollUrl": "/api/operations/op_01hxyz"
  }
  ```
</CodeGroup>

### Response fields

| Field                | Type   | Description                              |
| -------------------- | ------ | ---------------------------------------- |
| `id` / `operationId` | string | Operation ID for polling                 |
| `status`             | string | `queued` immediately after submission    |
| `pollUrl`            | string | URL to poll for status and final results |

### CompanyCard fields

| Field                         | Type      | Description                                         |
| ----------------------------- | --------- | --------------------------------------------------- |
| `id`                          | string    | Unique company identifier                           |
| `name`                        | string    | Company display name                                |
| `domain`                      | string    | Primary domain                                      |
| `website`                     | string    | Full website URL                                    |
| `industry`                    | string    | Industry classification                             |
| `employee_count`              | number    | Headcount                                           |
| `location`                    | string    | Headquarters location                               |
| `founding_year`               | number    | Year the company was founded                        |
| `revenue_min` / `revenue_max` | number    | Annual revenue range in USD                         |
| `tech_stack`                  | string\[] | Technologies and tools detected                     |
| `is_hiring`                   | boolean   | Whether the company is actively hiring              |
| `has_recent_funding`          | boolean   | Whether the company has had recent funding activity |
| `growth_band`                 | string    | `"low"`, `"medium"`, or `"high"`                    |
| `match_score`                 | number    | Relevance score from 0 to 1                         |
| `signal_summary`              | string\[] | Short human-readable signal descriptions            |

## Steps to build a target account list

<Steps>
  <Step title="Start with a broad query">
    Run a search with a broad `query` and a small `limit` to gauge the universe of matching companies.
  </Step>

  <Step title="Layer in technographic filters">
    Add technologies your product integrates with or competes against directly into the natural-language `query`.
  </Step>

  <Step title="Add buying signals">
    Add `filters.signals` values such as `"hiring"` or `"funding"` to surface companies in an active growth phase.
  </Step>

  <Step title="Paginate through results">
    Use `limit` to control the number of results returned by each search operation.
  </Step>

  <Step title="Drill into people">
    Use the returned company domain or name in `filters.company` on `POST /api/v1/people/search` to find contacts at that account.
  </Step>
</Steps>