> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enginy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Searching Contacts And Companies

> How to use `/v1/contacts/search` and `/v1/companies/search`, which filter keys matter most, and how to use the fields endpoints as the schema source of truth

## Overview

Use these endpoints when you need more than the basic list query params:

* `POST /v1/contacts/search`
* `POST /v1/companies/search`

The search endpoints support:

* `search` for full-text matching
* `include` for positive filters
* `exclude` for negative filters
* `page` and `pageSize` for pagination
* `fields` on contact search when you want extra contact/company-backed fields returned

## Start With The Fields Endpoints

Treat the fields endpoints as the schema source of truth for filtering:

* `GET /v1/contacts/fields`
* `GET /v1/companies/fields`

Each field object tells you:

* `id`: the exact key to use in `include`, `exclude`, and contact `fields`
* `label`: the human-readable name
* `dataType`: how to shape the filter value
* `fieldType`: whether the field is standard, AI, CRM, formula, or empty

For contact search, `GET /v1/contacts/fields` already includes valid company-backed field IDs such as `companyName`, so start there first.

If your workspace exposes scoring fields like `icpScore`, `scoreBand`, or custom AI/formula fields, use the exact `id` returned by the fields endpoint before adding them to search filters.

## Important Filters First

These are the highest-signal filters to reach for first:

1. `id`
   If you already know a single record ID, prefer `GET /v1/contacts/{contactId}` or `GET /v1/companies/{companyId}`. Use `id` inside search when you need to combine exact IDs with other filters.
2. `leadsGroup` or `companyGroup`
   List IDs for contact lists or company lists.
3. `campaigns`
   Campaign IDs when you want outreach-related slices.
4. `isInCRM` or `isCompanyInCRM`
   CRM presence filters.
5. `leadsCount` or `numberOfEmployees`
   Good first-pass sizing filters for companies and account selection.
6. Workspace scoring fields like `icpScore`
   Use only after confirming the field exists in `/fields`.

## Filter Value Schema

`include` and `exclude` are plain JSON objects whose keys are special filter names or field IDs from `/fields`.

Use these value shapes:

| Field type                               | Value shape                           | Example                                                                       |
| ---------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------- |
| Text / select / formula / AI / CRM field | Array of exact values                 | `"jobTitle": ["CEO", "Founder"]`                                              |
| Numeric field                            | Two-item min/max range array          | `"numberOfEmployees": ["50", "500"]`                                          |
| Boolean field                            | One-item boolean array                | `"isInCRM": [true]`                                                           |
| Timestamp field                          | Object with `startDate` and `endDate` | `"lastActivityAtCRM": { "startDate": "2026-01-01", "endDate": "2026-01-31" }` |
| Empty value match                        | Include an empty string in the array  | `"professionalEmail": [""]`                                                   |

Notes:

* Range filters are inclusive.
* You can leave one side open for numeric ranges, for example `["80", ""]`.
* Contact search also accepts company-backed field IDs in `include`, `exclude`, and `fields`.

## Contact Search Examples

### Contact list ID + CRM presence

```json theme={null}
{
  "page": 1,
  "pageSize": 25,
  "search": "growth",
  "fields": ["firstName", "lastName", "jobTitle", "companyName", "professionalEmail"],
  "include": {
    "leadsGroup": [123],
    "isInCRM": [true]
  }
}
```

### Contact IDs + company-backed filters

```json theme={null}
{
  "page": 1,
  "pageSize": 25,
  "include": {
    "id": [101, 205],
    "companyName": ["Stripe", "HubSpot"],
    "industry": ["Software"],
    "numberOfEmployees": ["50", "500"]
  },
  "exclude": {
    "campaigns": [77]
  }
}
```

### Workspace scoring field

Replace `icpScore` with the exact scoring field ID from `GET /v1/contacts/fields`.

```json theme={null}
{
  "page": 1,
  "pageSize": 25,
  "include": {
    "leadsGroup": [123],
    "icpScore": ["80", "100"]
  }
}
```

## Company Search Examples

### Company list ID + employee range

```json theme={null}
{
  "page": 1,
  "pageSize": 25,
  "search": "analytics",
  "include": {
    "companyGroup": [42],
    "industry": ["Software"],
    "numberOfEmployees": ["50", "500"]
  }
}
```

### Company IDs + lead count + CRM presence

```json theme={null}
{
  "page": 1,
  "pageSize": 25,
  "include": {
    "id": [101, 205],
    "leadsCount": ["5", "50"],
    "isCompanyInCRM": [true]
  },
  "exclude": {
    "campaigns": [88]
  }
}
```

### Workspace scoring field

Replace `scoreBand` with the exact scoring field ID from `GET /v1/companies/fields`.

```json theme={null}
{
  "page": 1,
  "pageSize": 25,
  "include": {
    "companyGroup": [42],
    "scoreBand": ["A"]
  }
}
```

## Reference Endpoints

* Contact fields: `GET /v1/contacts/fields`
* Company fields: `GET /v1/companies/fields`
* Contact search: `POST /v1/contacts/search`
* Company search: `POST /v1/companies/search`