> ## 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. # 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_READ` > > **Rate limit:** 100 requests per minute ## OpenAPI ````yaml https://openapi.enginy.ai/definitions.json post /v1/contacts/search openapi: 3.1.0 info: title: Enginy API version: 1.0.0 description: Public API for Enginy platform servers: - url: https://openapi.enginy.ai description: Configured server security: [] tags: - name: AI Variables description: >- Manage AI variables and discover the entity fields you can reference in prompts and entity requests. - name: Inbox description: >- Inbox endpoints for listing contact threads, reading thread messages, managing tags, and sending manual replies. - name: Workflows description: >- Build, validate, publish, run, and inspect advanced (graph) workflows, plus the block/condition catalog needed to author a workflow plan. paths: /v1/contacts/search: post: tags: - Contacts summary: Search contacts with advanced filters description: >- 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_READ` > > **Rate limit:** 100 requests per minute requestBody: content: application/json: schema: type: object properties: page: type: integer minimum: 1 default: 1 description: Page number for pagination. Minimum value is 1. pageSize: type: integer minimum: 1 maximum: 100 default: 25 description: Number of items per page. Minimum is 1, maximum is 100. search: type: string description: Search term for full-text search across contact fields. include: type: object additionalProperties: {} default: {} description: >- 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. exclude: type: object additionalProperties: {} default: {} description: >- 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. actionsId: type: integer description: >- 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). fields: type: array items: type: string default: [] description: >- 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. examples: byListIdAndCrmPresence: summary: Filter contacts by contact list ID and CRM presence value: page: 1 pageSize: 25 search: growth fields: - firstName - lastName - jobTitle - companyName - professionalEmail include: leadsGroup: - 123 isInCRM: - true byIdsAndCompanyFields: summary: Filter contacts by contact IDs and company-backed fields value: page: 1 pageSize: 25 include: id: - 101 - 205 companyName: - Stripe - HubSpot industry: - Software numberOfEmployees: - '50' - '500' exclude: campaigns: - 77 scoringFieldExample: summary: >- Filter contacts by a workspace-specific scoring field from the fields endpoint value: page: 1 pageSize: 25 include: leadsGroup: - 123 icpScore: - '80' - '100' responses: '200': description: Successful response with paginated contacts content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: number description: Unique identifier for the contact appUrl: type: string format: uri description: Direct Enginy app URL for opening this contact. firstName: type: - string - 'null' description: First name of the contact lastName: type: - string - 'null' description: Last name of the contact jobTitle: type: - string - 'null' description: Job title of the contact jobFunction: type: - string - 'null' description: >- Job function of the contact (e.g. "Sales", "Engineering"). Null when unknown. jobLevel: type: - string - 'null' description: >- Seniority level of the contact (e.g. "VP", "Director"). Null when unknown. linkedInProfileUrl: type: - string - 'null' description: LinkedIn profile URL of the contact professionalEmail: type: - string - 'null' description: Professional email address of the contact personalEmails: type: - string - 'null' description: Personal email addresses (comma-separated) mobilePhone: type: - string - 'null' description: Mobile phone number of the contact phones: type: - string - 'null' description: Other phone numbers (comma-separated) imageUrl: type: - string - 'null' description: Profile image URL companyId: type: - number - 'null' description: ID of the company associated with the contact company: type: - object - 'null' properties: id: type: number description: Company ID appUrl: type: string format: uri description: >- Direct Enginy app URL for opening the associated company. name: type: - string - 'null' description: Company name domain: type: - string - 'null' description: Company website domain companyLinkedInUrl: type: - string - 'null' description: Company LinkedIn URL required: - id - appUrl - name - domain - companyLinkedInUrl description: Company details emailVerificationStatus: type: string description: Email verification status contactCountry: type: - string - 'null' description: Country of the contact linkedInHeadline: type: - string - 'null' description: LinkedIn headline numberOfConnections: type: - number - 'null' description: Number of LinkedIn connections contactCRMId: type: - string - 'null' description: CRM contact ID leadCRMId: type: - string - 'null' description: CRM lead ID isInCRM: type: boolean description: Whether the contact is synced with CRM lastContactedAt: type: - string - 'null' format: date-time description: >- Date and time of the most recent outbound message sent to this contact across all campaigns. Null when the contact has never been messaged. smartFieldExplanations: type: object additionalProperties: type: string description: >- Map of smart field names to their explanation (returned when smart fields are requested). createdAt: type: string format: date-time description: Date and time when the contact was created updatedAt: type: string format: date-time description: Date and time when the contact was last updated required: - id - appUrl - firstName - lastName - jobTitle - jobFunction - jobLevel - linkedInProfileUrl - professionalEmail - personalEmails - mobilePhone - phones - imageUrl - companyId - company - emailVerificationStatus - contactCountry - linkedInHeadline - numberOfConnections - contactCRMId - leadCRMId - isInCRM - lastContactedAt - createdAt - updatedAt meta: type: object properties: page: type: number pageSize: type: number total: type: number required: - page - pageSize - total required: - data - meta '404': description: Actions run not found (when filtering by actionsId) security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ````