{
"data": [
{
"id": 123,
"appUrl": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"jobTitle": "<string>",
"jobFunction": "<string>",
"jobLevel": "<string>",
"linkedInProfileUrl": "<string>",
"professionalEmail": "<string>",
"personalEmails": "<string>",
"mobilePhone": "<string>",
"phones": "<string>",
"imageUrl": "<string>",
"companyId": 123,
"company": {
"id": 123,
"appUrl": "<string>",
"name": "<string>",
"domain": "<string>",
"companyLinkedInUrl": "<string>"
},
"emailVerificationStatus": "<string>",
"contactCountry": "<string>",
"linkedInHeadline": "<string>",
"numberOfConnections": 123,
"contactCRMId": "<string>",
"leadCRMId": "<string>",
"isInCRM": true,
"tags": [
{
"id": 123,
"name": "<string>",
"color": "<string>"
}
],
"lastContactedAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"smartFieldExplanations": {}
}
],
"meta": {
"page": 123,
"pageSize": 123,
"total": 123
}
}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. This is also the endpoint for per-contact campaign engagement, e.g. which contacts accepted a LinkedIn connection request (optionally without having been messaged yet): pair campaigns with the campaignLeadStatus filter — see the include/exclude schema descriptions for the supported values and the full flow.
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
{
"data": [
{
"id": 123,
"appUrl": "<string>",
"firstName": "<string>",
"lastName": "<string>",
"jobTitle": "<string>",
"jobFunction": "<string>",
"jobLevel": "<string>",
"linkedInProfileUrl": "<string>",
"professionalEmail": "<string>",
"personalEmails": "<string>",
"mobilePhone": "<string>",
"phones": "<string>",
"imageUrl": "<string>",
"companyId": 123,
"company": {
"id": 123,
"appUrl": "<string>",
"name": "<string>",
"domain": "<string>",
"companyLinkedInUrl": "<string>"
},
"emailVerificationStatus": "<string>",
"contactCountry": "<string>",
"linkedInHeadline": "<string>",
"numberOfConnections": 123,
"contactCRMId": "<string>",
"leadCRMId": "<string>",
"isInCRM": true,
"tags": [
{
"id": 123,
"name": "<string>",
"color": "<string>"
}
],
"lastContactedAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"smartFieldExplanations": {}
}
],
"meta": {
"page": 123,
"pageSize": 123,
"total": 123
}
}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, contactTags, 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). contactTags filters by the tags applied to the contact: tag IDs from GET /v1/contacts/tags (numbers or strings), with "" meaning no tag; in include a contact matches any of them, in exclude none. It needs contact and company tags on the workspace, otherwise the search answers 400 ENTITY_TAGS_NOT_ENABLED. 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.
Show child attributes
Show child attributes
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). contactTags filters by the tags applied to the contact: tag IDs from GET /v1/contacts/tags (numbers or strings), with "" meaning no tag; in include a contact matches any of them, in exclude none. It needs contact and company tags on the workspace, otherwise the search answers 400 ENTITY_TAGS_NOT_ENABLED. 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.
Show child attributes
Show child attributes
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. Through MCP, each contact contains only these fields plus id and appUrl; over REST they are added to the full contact. Use GET /v1/contacts/fields (MCP tool get_contact_field_metadata) to discover valid contact field names.