> ## 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.

# Find People with The Hog

> Discover ICP-matched contacts with natural language queries, then enrich the contacts you want to reach.

Use the people search endpoint to find contacts using a natural language query, optionally scoped to a specific company or filtered by title and location. Then submit selected contacts to the enrichment endpoint to retrieve verified contact data.

## Endpoint overview

| Endpoint                         | Method | What it does                                       |
| -------------------------------- | ------ | -------------------------------------------------- |
| `/api/v1/people/search/estimate` | POST   | Estimate people search and contact-enrichment risk |
| `/api/v1/people/search`          | POST   | Find ICP-matched people via NL query               |
| `/api/enrichments`               | POST   | Enrich selected contacts                           |

***

## People search

Use this endpoint to queue a contact discovery job from a natural language description. The API returns `202 Accepted` immediately; poll the returned URL to retrieve semantically ranked results.

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

Run `POST /api/v1/people/search/estimate` with the same body first when you want
to size `maxCredits`. The estimate response returns the standard estimate fields
plus a breakdown of the base people search credits and contact enrichment risk.
The base people-search estimate scales with requested provider-result pages, so
larger `limit` values can raise the preflight ceiling even without contact
enrichment.

### Request fields

| Field               | Type      | Required | Description                                                                                          |
| ------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `query`             | string    | Yes      | Natural language description, e.g. `"VP of Sales at a Series B SaaS company"`                        |
| `limit`             | number    | No       | Maximum contacts to return; between 1 and 100                                                        |
| `includeSignals`    | boolean   | No       | Include signal context in results                                                                    |
| `includeContacts`   | boolean   | No       | Include contact fields when available. When `contactFields` is omitted, this requests email + phone. |
| `contactFields`     | string\[] | No       | Contact fields to enrich when `includeContacts` is true. Allowed values: `"email"` and `"phone"`.    |
| `maxCredits`        | number    | No       | Maximum credits the operation may charge after metered usage is priced.                              |
| `filters.titles`    | string\[] | No       | Exact or partial title filters (e.g. `["VP Sales", "Head of Revenue"]`)                              |
| `filters.locations` | string\[] | No       | Location filters (e.g. `["New York", "London"]`)                                                     |
| `filters.company`   | object    | No       | Company filters such as `names`, `domains`, `industries`, or `employeeCount`                         |

### Contact enrichment spend controls

Set `includeContacts: true` only when you want people search to run contact enrichment as part of the search job. Use `contactFields` to request email-only, phone-only, or both. For backward compatibility, `includeContacts: true` without `contactFields` requests both email and phone.

Use `maxCredits` to cap the final customer charge for the operation. The API
also checks the conservative preflight estimate before paid people or contact
enrichment work starts. If `maxCredits` is lower than that preflight ceiling,
the request fails with `402 Payment Required` and no paid people/contact work
starts. Actual billing is based on measured usage and can be lower than the cap.

### Target account matching

Use `filters.company.domains` or `filters.company.names` for target-account search. These fields represent the company you asked for. A `filters.company.linkedinUrls` value can help when you already know the exact company page, but it is treated as a platform handle rather than the canonical account identity.

When a search is scoped to target accounts, poll `GET /api/operations/:id` and inspect `result.meta`:

| Field                     | Meaning                                                                                                                                                                                                                                                                                      |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `targetAccountSearchMode` | `linkedin_company_page` means results were constrained by a LinkedIn company page. `profile_current_company` means results were matched against current profile company text. `unavailable` means The Hog could not confidently search the requested account with the available search path. |
| `targetAccountOutcome`    | Explains the LinkedIn company-handle path: supplied, verified, unavailable/conflicting, or unresolved. Use `targetAccountSearchMode` to see how people were actually matched.                                                                                                                |
| `message`                 | Human-readable guidance for empty or unavailable results.                                                                                                                                                                                                                                    |

Each returned person may include `companyMatchEvidence` with `company_page` or `profile_current_job`, so you can tell why the person matched the account.

### Examples

<CodeGroup>
  ```bash Search for VP of Sales contacts theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://developer.thehog.ai/api/v1/people/search \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "VP of Sales at a B2B SaaS company",
      "limit": 25
    }'
  ```

  ```bash Scoped to a company with title and location filters theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://developer.thehog.ai/api/v1/people/search \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "revenue leader",
      "filters": {
        "titles": ["VP Sales", "Chief Revenue Officer", "Head of Sales"],
        "locations": ["United States", "Canada"],
        "company": { "domains": ["salesforce.com"] }
      },
      "limit": 10
    }'
  ```

  ```bash Title filters with signals theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://developer.thehog.ai/api/v1/people/search \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "growth-focused marketing leader",
      "filters": {
        "titles": ["VP Marketing", "Head of Growth"]
      },
      "includeSignals": true,
      "limit": 50
  }'
  ```

  ```bash Email-only contact enrichment with a credit cap theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://developer.thehog.ai/api/v1/people/search \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "VP Engineering at B2B SaaS companies",
      "limit": 25,
      "includeContacts": true,
      "contactFields": ["email"],
      "maxCredits": 63750
    }'
  ```

  ```bash Estimate before queueing contact enrichment theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://developer.thehog.ai/api/v1/people/search/estimate \
    -H "X-Access-Key: ak_xxxxxxxxxxxxxxxx" \
    -H "X-Secret-Key: sk_xxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "VP Engineering at B2B SaaS companies",
      "limit": 25,
      "includeContacts": true,
      "contactFields": ["email"]
    }'
  ```
</CodeGroup>

### Response

The search returns HTTP `202` with an operation ID and poll URL.

```json theme={null} theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "op_01hxyz",
  "operationId": "op_01hxyz",
  "status": "queued",
  "pollUrl": "/api/operations/op_01hxyz",
  "meta": {
    "requestId": "req_01hxyz"
  }
}
```

## Typical workflow

<Steps>
  <Step title="Search for target companies">
    Use `POST /api/v1/companies/search` with firmographic and signal filters to build your target account list. Note the `id` of each company you want to prospect.
  </Step>

  <Step title="Find contacts at each account">
    Pass company constraints in `filters.company` along with a role-based `query`
    (e.g. `"Head of Engineering"`) to surface relevant contacts.
  </Step>

  <Step title="Enrich with contact data">
    Pass the person `id` from search results to `POST /api/enrichments` to retrieve verified email addresses and phone numbers.
  </Step>
</Steps>

<Tip>
  Use `filters.company.domains` or `filters.company.names` to scope people
  search to specific accounts — this significantly improves relevance compared
  to a global search with the same query.
</Tip>