Search contacts with advanced filters

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. Per-contact campaign engagement — including LinkedIn connection-request status — is available through the campaign-scoped campaignLeadStatus filter. It is not a contact field, so it never appears in the fields catalog, and it is ignored unless include.campaigns is also set; both include.campaignLeadStatus and exclude.campaignLeadStatus are evaluated against the campaigns in include.campaigns. Supported values: linkedinConnectionSent, linkedinConnectionRequestAccepted, sentAtLeastOneMessage, replied, seenMessage, linkedinConversationViewed, clickedConversations, bouncedMessages, linkedinConnectionsSentNotByPlatform. Exception: linkedinConnectionsSentNotByPlatform is not campaign-scoped — it matches any connection request to the contact that was not sent through Enginy, whatever the campaign. Flow to list contacts who accepted a LinkedIn connection request but have not been messaged yet: find the campaign ID with GET /v1/campaigns (MCP tool get_campaigns), then search with include { "campaigns": ["<campaignId>"], "campaignLeadStatus": ["linkedinConnectionRequestAccepted"] } and exclude { "campaignLeadStatus": ["sentAtLeastOneMessage"] }, requesting the contact fields you need (e.g. fields: ["firstName", "lastName", "jobTitle"]). Caveat: connection acceptance is tracked per contact + sender identity, so an acceptance obtained through another campaign that uses the same sender identity also matches, and counts can differ slightly from campaign analytics (which additionally check acceptance timing against the connection step). 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. Per-contact campaign engagement — including LinkedIn connection-request status — is available through the campaign-scoped campaignLeadStatus filter. It is not a contact field, so it never appears in the fields catalog, and it is ignored unless include.campaigns is also set; both include.campaignLeadStatus and exclude.campaignLeadStatus are evaluated against the campaigns in include.campaigns. Supported values: linkedinConnectionSent, linkedinConnectionRequestAccepted, sentAtLeastOneMessage, replied, seenMessage, linkedinConversationViewed, clickedConversations, bouncedMessages, linkedinConnectionsSentNotByPlatform. Exception: linkedinConnectionsSentNotByPlatform is not campaign-scoped — it matches any connection request to the contact that was not sent through Enginy, whatever the campaign. Flow to list contacts who accepted a LinkedIn connection request but have not been messaged yet: find the campaign ID with GET /v1/campaigns (MCP tool get_campaigns), then search with include { "campaigns": ["<campaignId>"], "campaignLeadStatus": ["linkedinConnectionRequestAccepted"] } and exclude { "campaignLeadStatus": ["sentAtLeastOneMessage"] }, requesting the contact fields you need (e.g. fields: ["firstName", "lastName", "jobTitle"]). Caveat: connection acceptance is tracked per contact + sender identity, so an acceptance obtained through another campaign that uses the same sender identity also matches, and counts can differ slightly from campaign analytics (which additionally check acceptance timing against the connection step). 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.