---
title: "Estimate people search"
method: POST
path: "/api/v1/people/search/estimate"
tags: ["People Search"]
---

# Estimate people search

`POST /api/v1/people/search/estimate`

Pre-flight conservative credit estimate for POST /api/v1/people/search. Includes contact enrichment assumptions when includeContacts is true.

## Request body

- PostPeopleSearchDto
  - `query` string, required
  - `limit` number
  - `includeSignals` boolean
  - `includeContacts` boolean
  - `contactFields` string[] — Contact fields to enrich when includeContacts is true. Omit to preserve legacy includeContacts=true behavior, which requests both email and phone.
  - `maxCredits` number — Maximum credits the people search operation may charge. When omitted, normal account limits apply.
  - `filters` EntitySearchFiltersDto
    - `titles` string[]
    - `titleMatch` 'exact' | 'similar'
    - `locations` string[]
    - `industries` string[]
    - `employeeCount` EntityEmployeeCountFilterDto
      - `min` number
      - `max` number
    - `signals` string[]
    - `company` EntityCompanyNestedFilterDto
      - `names` string[]
      - `domains` string[]
      - `linkedinUrls` string[]
      - `industries` string[]
      - `employeeCount` EntityEmployeeCountFilterDto
        - `min` number
        - `max` number
      - `signals` string[]
  - `confirm` boolean

## Response `200`

Conservative people search preflight estimate and contact enrichment breakdown.

- PeopleSearchEstimateDto
  - `estimatedCredits` number, required — Estimated credits to be consumed
  - `likelySyncOrAsync` 'sync' | 'async', required — Whether the real request will return 200 or 202
  - `expectedLatencyRange` string
  - `withinPlanLimits` boolean, required
  - `breakdown` PeopleSearchEstimateBreakdownDto, required
    - `baseSearchCredits` number, required — Conservative base estimate for the people discovery work.
    - `contactEnrichment` PeopleSearchEstimateContactBreakdownDto, required
      - `includeContacts` boolean, required
      - `fields` string[], required — Requested contact fields included in the estimate. Empty when includeContacts is false.
      - `maxPeople` number, required — Maximum people count used for contact enrichment cost risk. This is the request limit after defaults are applied.
      - `contactAttemptsPerFieldPerPerson` number, required — Worst-case contact enrichment attempts assumed for each requested contact field on each returned person.
      - `estimatedCredits` number, required — Estimated contact enrichment credits included in estimatedCredits.
  - `assumptions` PeopleSearchEstimateAssumptionsDto, required
    - `mode` string, required
    - `description` string, required — Human-readable explanation of the conservative estimate assumptions.

## Other responses

- `400` — The request body or parameters are invalid.
- `401` — Authentication is required.
- `500` — An unexpected error occurred.

---

[API](https://skmtc.net/thehog/apis/the-hog-api.md) · [All operations](https://skmtc.net/thehog/apis/the-hog-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/thehog/the-hog-api/revisions/f5056017668a/schema)