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

# list_contacts

> List contacts (profiles) created within a date range, or look them up by exact email address, with optional custom-field include and value filtering.

Returns one row per contact (profile) created in the date range, or matching an exact email address, with primary email, name, phone, and location. Optionally enriched with all known emails, Cometly tracking tokens, or the full set of custom profile fields.

## When to use

* *"Who signed up last week?"*
* *"List leads from this month."*
* *"Show me new contacts created today."*
* *"Find contacts where Customer Plan is Premium."*
* *"Do we have a contact for [jane@acme.com](mailto:jane@acme.com)?"* → pass `email`, no date range needed.

For a single contact's full journey, use [`get_contact`](https://docs.cometly.com/mcp/tools/get-contact). For ad-performance questions, use [`query_ad_metrics`](https://docs.cometly.com/mcp/tools/query-ad-metrics). Searching for a specific named person by name should go through `search_workspace` first — but an exact email address is better served by this tool's `email` parameter.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `start_date` | string | Conditional | `YYYY-MM-DD HH:MM:SS`, interpreted in your Space's timezone. Filters by contact creation date. Required unless `email` is supplied, and must be sent as a pair with `end_date`. |
| `end_date` | string | Conditional | `YYYY-MM-DD HH:MM:SS`, must be after `start_date`. Required unless `email` is supplied, and must be sent as a pair with `start_date`. |
| `email` | string\[] | No | Look contacts up by exact email address instead of (or alongside) the date range. Matching is exact and case-insensitive. Matches both the contact's primary address and any of its alternate addresses, including addresses captured on profiles later merged into the contact. Up to 100 addresses per call. A contact matched on an alternate address comes back with its *primary* in `email`, not the address you queried — set `include_all_emails` when passing more than one address, or you cannot tell which input produced which row. |
| `per_page` | integer | No | 1–5000. Default 200. |
| `cursor` | string | No | Pagination cursor from a prior response's `next_cursor`. |
| `include_all_emails` | boolean | No | Adds an array of all known email addresses per contact (including merged profiles). |
| `include_comet_tokens` | boolean | No | Adds the contact's last 5 Cometly tracking tokens. |
| `include_custom_fields` | boolean | No | Includes the 30 custom profile fields (`profile_field_1` through `profile_field_30`). |
| `use_custom_field_labels` | boolean | No | When `include_custom_fields` is true, replaces raw column names with user-defined labels (e.g. `"Customer Age"`). Always set this to true unless the user explicitly wants raw column names. |
| `custom_field_filters` | array | No | AND-joined conditions on custom profile fields. See below. |

## Custom field filters

Flat array of AND-joined conditions referencing slots configured on your Space:

```json theme={null}
[
  { "field": "profile_field_5",  "operator": "equal_to",     "value": "Premium" },
  { "field": "profile_field_18", "operator": "greater_than", "value": 30 },
  { "field": "profile_field_27", "operator": "between",      "start": "2025-01-01", "end": "2025-12-31" }
]
```

The tool's input schema lists the **labels and types your Space has configured** for slots 1–30, so the model picks the right slug automatically when you mention a user-facing label like "Customer Plan" or "Customer Age." Slots that haven't been configured are rejected with `validation_error`. Maximum 10 conditions per request.

### Operator vocabulary by field type

| Slot range | Type | Operators |
| - | - | - |
| `profile_field_1` – `profile_field_15` | text | `equal_to`, `not_equal_to`, `contains`, `not_contains`, `starts_with`, `ends_with`, `contains_word`, `any`, `unknown` |
| `profile_field_16` – `profile_field_25` | number | `equal_to`, `not_equal_to`, `greater_than`, `greater_than_or_equal_to`, `less_than`, `less_than_or_equal_to`, `any`, `unknown` |
| `profile_field_26` – `profile_field_30` | date | `equal_to`, `between`, `greater_than`, `less_than`, `age_greater_than`, `age_equal_to`, `age_less_than`, `any`, `unknown` |

`any` matches contacts where the field has a value; `unknown` matches contacts where the field is empty or unset. For numeric fields, `any` requires a value greater than `0` and `unknown` matches `0` or unset. Date comparisons (`equal_to`, `greater_than`, `less_than`, `between`) use your space's configured timezone; `equal_to` matches the full calendar day.

## Example response

```json theme={null}
{
  "data": [
    {
      "id": 41902,
      "email": "jane@example.com",
      "name": "Jane Doe",
      "phone": null,
      "location": "Austin, TX, US",
      "Customer Plan": "Premium",
      "Customer Age": 34
    }
  ],
  "next_cursor": "eyJpZCI6NDE5MDJ9",
  "prev_cursor": null,
  "per_page": 200
}
```

When `use_custom_field_labels` is true, the response keys carry the labels you configured (`"Customer Plan"`, `"Customer Age"`); otherwise they appear as raw `profile_field_N` keys.

## Caveats

* **Primary data only.** The list endpoint returns one email, name, phone, and location per contact. For all known values across merged profiles, use [`get_contact`](https://docs.cometly.com/mcp/tools/get-contact) or pass `include_all_emails: true`.
* **Order is newest first** by `id` descending. Cursor pagination uses `id` as the cursor key.
* **Empty filter slots are rejected.** Filtering on `profile_field_19` when slot 19 has no label returns a validation error rather than silently returning zero rows.
* **`not_equal_to` / `not_contains` exclude unset values.** Contacts where the field is unset are not included. Add a separate `unknown` condition if you need to capture those.
* **`email` is an array only.** Unlike the HTTP endpoint's query string, the MCP tool's input schema doesn't accept a comma-separated string for `email` — always pass an array of addresses, even for a single lookup.
* **No match is not an error.** An `email` (or date range) with no matching contacts returns an empty `data` array, not a validation error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.