Search contacts with advanced filters
Search contacts with advanced filtering options. Every key in include/exclude must be a recognized filter field (a static filter like id, leadsGroup, or campaigns, or a contact/company field id returned by the fields endpoints) — an unrecognized key returns a 400 listing the offending key(s) instead of being silently ignored. To filter contacts by the contact’s own country, use leadCountry (this same field is returned in responses as contactCountry and accepted as a write alias on update/create). The country filter key matches the associated company’s country instead, not the contact’s own.
Responses include direct Enginy app URLs when available. Each returned contact includes an appUrl field, and associated companies include appUrl when present. MCP agents should return those URLs to users whenever they are present in the response.
Required scope:
CONTACTS_READRate limit: 100 requests per minute
Authorizations
Body
Page number for pagination. Minimum value is 1.
x >= 1Number of items per page. Minimum is 1, maximum is 100.
1 <= x <= 100Search term for full-text search across contact fields.
Filter conditions to include. Supports special filters like id, campaigns, leadsGroup, companyGroup, isInCRM, enrichments, and any contact/company field ID returned by the fields endpoints. Filter values should match the field data type returned by GET /v1/contacts/fields: text/select fields use arrays of exact values, numeric fields use two-item range arrays like ["10","100"], boolean fields use one-item arrays like [true], and timestamp fields use { "startDate": "...", "endDate": "..." }. Start with id, leadsGroup (contact list IDs), companyGroup (company list IDs), campaigns, isInCRM, and any workspace scoring fields such as icpScore or scoreBand when those field IDs appear in the fields response. To filter contacts by the contact's own country, use leadCountry (this same field is returned in responses as contactCountry and accepted as a write alias on update/create). The country filter key matches the associated company's country instead, not the contact's own. Unrecognized keys are rejected with a 400 rather than silently ignored. Use GET /v1/contacts/fields (MCP tool get_contact_field_metadata) to discover valid contact field names for fields, include, exclude, and update payloads. Company-backed filters can use use get /v1/companies/fields (mcp tool get_company_field_metadata) to discover valid company field names.
Filter conditions to exclude. Same structure as include. Filter values should match the field data type returned by GET /v1/contacts/fields: text/select fields use arrays of exact values, numeric fields use two-item range arrays like ["10","100"], boolean fields use one-item arrays like [true], and timestamp fields use { "startDate": "...", "endDate": "..." }. Start with id, leadsGroup (contact list IDs), companyGroup (company list IDs), campaigns, isInCRM, and any workspace scoring fields such as icpScore or scoreBand when those field IDs appear in the fields response. To filter contacts by the contact's own country, use leadCountry (this same field is returned in responses as contactCountry and accepted as a write alias on update/create). The country filter key matches the associated company's country instead, not the contact's own. Unrecognized keys are rejected with a 400 rather than silently ignored. Use GET /v1/contacts/fields (MCP tool get_contact_field_metadata) to discover valid contact field names for fields, include, exclude, and update payloads.
Filter contacts by a specific actions run ID. Returns only contacts that were created or processed as part of this actions run (e.g., from "Search contacts from company" action).
Specific contact fields to include in the response. Use GET /v1/contacts/fields (MCP tool get_contact_field_metadata) to discover valid contact field names.