---
title: "Search contacts by filters"
method: POST
path: "/api/employees/contact-finder"
tags: ["Contact Finder"]
---

# Search contacts by filters

`POST /api/employees/contact-finder`

## Request

- Base URL: `https://quickenrich.io`
- URL: `https://quickenrich.io/api/employees/contact-finder`
- Auth: HTTP bearer

Filter-based contact search. Email and phone values are masked (`has_email` / `has_phone`); use `/reveal` to unlock contact details.

At least one filter is required: a non-empty include/exclude dimension, `has_email`, or `has_phone`.

Constrained dimensions (`country_code`, `industry_linkedin`, `number_of_employees`, `revenue`, `services`) must use exact values from the Lookups endpoints. Max 100 values per include/exclude list.

Offset `page` pagination is limited to the first 10,000 results. To continue, pass `meta.next_cursor` as `cursor` (page is ignored when cursor is set).

## Request body

- ContactFinderSearchRequest
  - `page` integer: Offset page. Limited to the first 10,000 results. Ignored when `cursor` is set.
  - `per_page` integer
  - `cursor` string: Opaque cursor from `meta.next_cursor`. Use to fetch past the first 10,000 rows. Echo unchanged.
  - `has_email` boolean
  - `has_phone` boolean
  - `company_name` IncludeExcludeFilter
    - `include` string[]
    - `exclude` string[]
  - `company_url` IncludeExcludeFilter
    - `include` string[]
    - `exclude` string[]
  - `city` IncludeExcludeFilter
    - `include` string[]
    - `exclude` string[]
  - `country_code` object: Exact values from GET /api/lookups/country-codes
    - `include` string[]
    - `exclude` string[]
  - `industry_linkedin` object: Exact values from GET /api/lookups/industries
    - `include` string[]
    - `exclude` string[]
  - `number_of_employees` object: Exact values from GET /api/lookups/employee-ranges
    - `include` string[]
    - `exclude` string[]
  - `revenue` object: Exact values from GET /api/lookups/revenue-ranges
    - `include` string[]
    - `exclude` string[]
  - `title` IncludeExcludeFilter
    - `include` string[]
    - `exclude` string[]
  - `locality` IncludeExcludeFilter
    - `include` string[]
    - `exclude` string[]
  - `bio_li` object: Full-text search against LinkedIn bio (max 500 chars per value)
    - `include` string[]
    - `exclude` string[]
  - `services` object: Exact values from GET /api/lookups/company-services
    - `include` string[]
    - `exclude` string[]

## Response `200`

Contacts fetched (credits_used is 0; search does not charge).

- object
  - `success` boolean, required
  - `message` string, required
  - `code` integer, required
  - `data` ContactFinderEmployee[]
    - `emp_id` integer, nullable
    - `first_name` string
    - `last_name` string
    - `title` string
    - `employee_linkedin` string
    - `has_email` boolean
    - `has_phone` boolean
    - `has_linkedin` boolean
    - `company_url` string
    - `company_name` string
    - `email_domain` string
    - `home_page_email` string
    - `company_linked` string
    - `company_phone` string
    - `industry` string
    - `revenue` string
    - `employee_count` string
    - `address1` string
    - `address2` string
    - `city` string
    - `region_code` string
    - `zip` string
    - `locality` string
    - `country_code` string
  - `meta` object
    - `page` integer
    - `per_page` integer
    - `total` integer
    - `last_page` integer
    - `credits_used` integer
    - `remaining_credits` integer
    - `next_cursor` string, nullable: Opaque cursor for the next page. Null when there are no more results. Pass this value as `cursor` to continue past the first 10,000 rows.
    - `has_more` boolean: True when more results can be fetched via `cursor`.
    - `max_pages` integer: Present on Free plans. Contact Finder and Company Finder search is limited to this many pages (5). Cursor pagination is not available.
    - `reason` string

## Other responses

- `401`: Missing, invalid, or inactive API key
- `422`: Validation failed
- `429`: Rate limit exceeded
- `500`: Upstream/search service error

---

[API](https://skmtc.dev/quickenrich/apis/quick-enrich-api.md) - [All operations](https://skmtc.dev/quickenrich/apis/quick-enrich-api/llms.txt) - [OpenAPI document](https://skmtc.dev/quickenrich/apis/quick-enrich-api/revisions/581bb7f6ae10?raw)