> ## Documentation Index > Fetch the complete documentation index at: https://docs.tryhuntr.com/llms.txt > Use this file to discover all available pages before exploring further. # People Search > Search contacts with structured filters, semantic_query, or email/phone availability flags. Returns one paginated page of people without email or phone values. ## OpenAPI ````yaml /openapi.json post /person-search openapi: 3.0.3 info: title: Huntr — The GTM Intelligence API description: >- Give AI agents company, people, contact, and web intelligence through one API. Search accounts, build targeted lists, enrich leads, find contacts, and uncover buying signals. **Authentication:** Authenticated endpoints require an `x-api-key` header with your Huntr API key. Get a key by signing up via `POST /keys/create`. Public endpoints (pricing, sign-up, health) work without a key. **Rate limit:** 5 requests/second per API key on authenticated endpoints. version: 2.0.0 servers: - url: https://api.tryhuntr.com security: [] tags: - name: Contact APIs description: >- Search people and enrich work email, phone, and reverse-email contact fields. - name: Company APIs description: >- Search companies and retrieve company-level attributes such as detected technology stack and active job postings. - name: Research APIs description: >- Research one company, person, team, or focused business question and return a sales-ready answer. Lite, standard, and deep tiers. - name: LinkedIn APIs description: >- LinkedIn URL discovery, company and profile pages, posts, reactions, and comments. - name: X APIs description: X profiles, posts, search results, and thread context. - name: Web APIs description: >- Find, scrape, and analyze pages on a domain, plus tech stack, domain contacts, and job postings. - name: Account description: >- Sign up, verify email, recover keys, check balance, view usage, add credits, and read the public pricing matrix. - name: System description: Health check. paths: /person-search: post: tags: - Contact APIs summary: People Search description: >- Search contacts with structured filters, semantic_query, or email/phone availability flags. Returns one paginated page of people without email or phone values. requestBody: required: true content: application/json: schema: type: object properties: semantic_query: type: string maxLength: 8000 description: >- Natural-language description of the people to find. Mutually exclusive with `query`. The response includes `resolved_query` for deterministic pagination. filters: type: object description: >- Hard filters for semantic_query. Same supported fields as query. properties: title: type: object description: Employee job title. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. locality: type: object description: Person locality, such as city, state, or country. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. company_name: type: object description: Current employer name. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. company_url: type: object description: Company website or domain. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. city: type: object description: Company city. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. country_code: type: object description: Alpha-2 country code. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. industry_linkedin: type: object description: Company industry label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. number_of_employees: type: object description: Company employee range label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. revenue: type: object description: Company revenue range label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. bio_li: type: object description: Company LinkedIn About text. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. services: type: object description: Company service label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. additionalProperties: false query: type: object description: >- At least one supported filter required unless has_email or has_phone is true. Use non-empty include and/or exclude arrays. properties: title: type: object description: Employee job title. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. locality: type: object description: Person locality, such as city, state, or country. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. company_name: type: object description: Current employer name. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. company_url: type: object description: Company website or domain. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. city: type: object description: Company city. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. country_code: type: object description: Alpha-2 country code. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. industry_linkedin: type: object description: Company industry label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. number_of_employees: type: object description: Company employee range label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. revenue: type: object description: Company revenue range label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. bio_li: type: object description: Company LinkedIn About text. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. services: type: object description: Company service label. properties: include: type: array items: type: string description: Values to match. exclude: type: array items: type: string description: Values to exclude. additionalProperties: false pagination: type: object description: >- Configurable page size. pagination.size min 1, default 100, max 200. Send pagination.size on the first request and with pagination.token on later pages. Keep the same query and has_email/has_phone flags between pages. properties: size: type: integer minimum: 1 maximum: 200 default: 100 description: >- Page size for this request. Min 1, default 100, max 200. Huntr returns up to this many people and charges per row returned. token: type: string description: >- Opaque cursor from the prior response. Omit on the first page. has_email: type: boolean description: When true, only return contacts with email data available. has_phone: type: boolean description: When true, only return contacts with phone data available. not: required: - query - semantic_query description: >- Choose one people search input: - Natural-language mode: send semantic_query. Add filters only with semantic_query when you need hard constraints. - Structured-filter mode: send query when you already have exact filters, or when paginating with a resolved_query. Optional: add has_email and/or has_phone to return only contacts with available email or phone data. Do not send query and semantic_query together. examples: semantic: summary: Natural-language people discovery with a hard location filter description: >- Natural-language mode: semantic_query describes the people to find. filters adds a hard location constraint. has_email keeps only contacts with email data available. value: semantic_query: VPs of Sales at cybersecurity companies filters: locality: include: - US has_email: true pagination: size: 10 by_title: summary: CTOs in the US description: >- Structured-filter mode: query contains exact title and location filters supplied by your code. value: query: title: include: - CTO - Chief Technical Officer locality: include: - US pagination: size: 10 by_company: summary: Engineers at a company description: >- Structured-filter mode: query contains exact title and current employer filters supplied by your code. value: query: title: include: - engineer company_name: include: - Stripe pagination: size: 5 responses: '200': description: Person search results. content: application/json: schema: type: object properties: success: type: boolean request_id: type: string result: type: object properties: people: type: array description: >- Matching contacts. Discovery results do not include email or phone values. items: type: object properties: name: type: string description: >- Convenience full name built from first and last name when available. first_name: type: string nullable: true last_name: type: string nullable: true title: type: string nullable: true linkedin_url: type: string nullable: true description: Employee LinkedIn profile URL. has_email: type: boolean description: >- Whether email data is available for this contact. has_phone: type: boolean description: >- Whether phone data is available for this contact. company_url: type: string nullable: true company_name: type: string nullable: true email_domain: type: string nullable: true home_page_email: type: string nullable: true city: type: string nullable: true locality: type: string nullable: true location: type: string nullable: true country_code: type: string nullable: true company_linkedin_url: type: string nullable: true industry: type: string nullable: true revenue: type: string nullable: true employee_count: type: string nullable: true address: type: string nullable: true region_code: type: string nullable: true additionalProperties: true pagination: type: object required: - size - token - has_more properties: size: type: number description: >- Number of people returned in result.people for this response page. token: type: string description: >- Opaque token for the next page. Null means there is no next page. nullable: true has_more: type: boolean description: >- Whether another page is available. When false, pagination.token is null. additionalProperties: false total: type: number description: >- Total matching records for the submitted query. This can be larger than the number returned in this page. price: type: number description: Plan-specific amount multiplied by people returned. credits_remaining: type: number required: - success - request_id - result - price - credits_remaining - pagination - total examples: found: summary: Contacts returned value: success: true request_id: req_1746123456_ps1x2y result: people: - name: Jane Doe first_name: Jane last_name: Doe title: Chief Executive Officer linkedin_url: https://linkedin.com/in/janedoe has_email: true has_phone: false company_url: https://example.com company_name: Example Corp email_domain: example.com home_page_email: info@example.com city: San Francisco locality: San Francisco Bay Area country_code: US pagination: size: 1 token: opaque-next-page-token has_more: true total: 842 price: 0.0003 credits_remaining: 4.9997 not_found: summary: No contacts returned value: success: true request_id: req_1746123456_ps2x3y result: people: [] pagination: size: 0 token: null has_more: false total: 0 price: 0 credits_remaining: 5 '400': description: Missing or invalid query. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Insufficient credits. content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- A constrained lookup filter contains a value outside the accepted list. content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Search failed. content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: >- The natural-language query could not be translated safely. No credits are charged. content: application/json: schema: $ref: '#/components/schemas/Error' security: - ApiKeyAuth: [] x-codeSamples: - lang: Shell label: Semantic query source: |- curl --request POST \ --url https://api.tryhuntr.com/person-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "semantic_query": "VPs of Sales at cybersecurity companies", "filters": { "locality": { "include": [ "US" ] } }, "has_email": true, "pagination": { "size": 10 } }' - lang: Shell label: Structured title filter source: |- curl --request POST \ --url https://api.tryhuntr.com/person-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "query": { "title": { "include": [ "CTO", "Chief Technical Officer" ] }, "locality": { "include": [ "US" ] } }, "pagination": { "size": 10 } }' - lang: Shell label: Company name filter source: |- curl --request POST \ --url https://api.tryhuntr.com/person-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "query": { "title": { "include": [ "engineer" ] }, "company_name": { "include": [ "Stripe" ] } }, "pagination": { "size": 5 } }' - lang: Shell label: Only contacts with email source: |- curl --request POST \ --url https://api.tryhuntr.com/person-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "has_email": true, "pagination": { "size": 10 } }' - lang: Shell label: Only contacts with phone source: |- curl --request POST \ --url https://api.tryhuntr.com/person-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "has_phone": true, "pagination": { "size": 10 } }' x-code-samples: - lang: Shell label: Semantic query source: |- curl --request POST \ --url https://api.tryhuntr.com/person-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "semantic_query": "VPs of Sales at cybersecurity companies", "filters": { "locality": { "include": [ "US" ] } }, "has_email": true, "pagination": { "size": 10 } }' - lang: Shell label: Structured title filter source: |- curl --request POST \ --url https://api.tryhuntr.com/person-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "query": { "title": { "include": [ "CTO", "Chief Technical Officer" ] }, "locality": { "include": [ "US" ] } }, "pagination": { "size": 10 } }' - lang: Shell label: Company name filter source: |- curl --request POST \ --url https://api.tryhuntr.com/person-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "query": { "title": { "include": [ "engineer" ] }, "company_name": { "include": [ "Stripe" ] } }, "pagination": { "size": 5 } }' - lang: Shell label: Only contacts with email source: |- curl --request POST \ --url https://api.tryhuntr.com/person-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "has_email": true, "pagination": { "size": 10 } }' - lang: Shell label: Only contacts with phone source: |- curl --request POST \ --url https://api.tryhuntr.com/person-search \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "has_phone": true, "pagination": { "size": 10 } }' components: schemas: Error: type: object properties: error: type: string description: Human-readable error message. required: - error securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Your Huntr API key. Get one at tryhuntr.com. Pass as x-api-key header on all authenticated requests. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.