# Search Contacts

Search and filter contacts. Returns a flat list of matching contacts.

Endpoint: POST /data-api/v2/contacts/search
Security: authorization

## Request fields (application/json):

  - `filters` (object, required)
    Filters object for contact search. All filters are inclusion-only.
    Example: {"companies":{"ids":["1698C53EBC888758570396E0334965C1"]},"contact_location":{"countries":["US"]},"job_functions":["Engineering"],"job_seniority":["Director"],"time_in_current_role":["company_veteran"…

  - `filters.companies` (object)
    Filter contacts by company. Provide either `ids` or `domains`, but not both.
    Example: {"ids":["1698C53EBC888758570396E0334965C1"]}

  - `filters.companies.domains` (array)
    List of company domains.

  - `filters.companies.ids` (array)
    List of hex-encoded HG company IDs.

  - `filters.contact_location` (object)
    Filter contacts by location.
    Example: {"countries":["US","CA"]}

  - `filters.contact_location.countries` (array)
    List of ISO 3166-1 alpha-2 country codes.

  - `filters.job_functions` (array)
    Filter by job function. Inclusion only.

  - `filters.job_seniority` (array)
    Filter by job seniority. Inclusion only.

  - `filters.time_in_current_role` (array)
    Filter by time in current role. Inclusion only.
Enum values:
- `new_change_maker`: New Change-Maker (< 6 months)
- `rising_contributor`: Rising Contributor (6 months - 1 year)
- `established_performer`: Established Performer (1-2 years)
- `stable_operator`: Stable Operator (3-5 years)
- `company_veteran`: Company Veteran (5+ years)

  - `limit` (integer)
    Maximum number of contacts to return

  - `offset` (integer)
    Number of contacts to skip (max 99)

## Response 200 fields (application/json):

  - `contacts` (array, required)

  - `contacts.company_domain` (string)
    Company domain

  - `contacts.company_id` (string)
    Company identifier

  - `contacts.company_name` (string)
    Company name

  - `contacts.contact_location_city` (string)
    Contact location city

  - `contacts.contact_location_country` (string)
    Contact location country

  - `contacts.contact_location_region` (string)
    Contact location region

  - `contacts.first_name` (string)
    Contact first name

  - `contacts.full_name` (string)
    Contact full name

  - `contacts.id` (string)
    Contact identifier

  - `contacts.job_functions` (array)
    Contact job functions

  - `contacts.job_seniority` (string)
    Contact job seniority

  - `contacts.job_title` (string)
    Contact job title

  - `contacts.last_name` (string)
    Contact last name

  - `contacts.linkedin_url` (string)
    Contact LinkedIn URL

  - `count` (integer)
    Total number of contacts matching the filters (before pagination)

## Response 401 fields (application/json):

  - `errors` (array)

  - `errors.detail` (string, required)
    Example: The api key provided is not valid

  - `errors.source` (string)

  - `errors.title` (string, required)
    Example: Unauthorized

## Response 422 fields (application/json):

  - `errors` (array, required)

  - `errors.detail` (string, required)
    Example: null value where string expected

  - `errors.source` (object, required)

  - `errors.source.pointer` (string, required)
    Example: /data/attributes/petName

  - `errors.title` (string, required)
    Example: Invalid value