> ## 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 companies with advanced filters > Search companies with advanced filtering options. Every key in `include`/`exclude` must be a recognized filter field (a static filter like `id`, `companyGroup`, or `campaigns`, or a company field id returned by the fields endpoint) — an unrecognized key returns a 400 listing the offending key(s) instead of being silently ignored. Responses include direct Enginy app URLs when available. Each returned company includes an `appUrl` field. MCP agents should return those URLs to users whenever they are present in the response. > **Required scope:** `COMPANIES_READ` > > **Rate limit:** 100 requests per minute ## OpenAPI ````yaml https://openapi.enginy.ai/definitions.json post /v1/companies/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/companies/search: post: tags: - Companies summary: Search companies with advanced filters description: >- Search companies with advanced filtering options. Every key in `include`/`exclude` must be a recognized filter field (a static filter like `id`, `companyGroup`, or `campaigns`, or a company field id returned by the fields endpoint) — an unrecognized key returns a 400 listing the offending key(s) instead of being silently ignored. Responses include direct Enginy app URLs when available. Each returned company includes an `appUrl` field. MCP agents should return those URLs to users whenever they are present in the response. > **Required scope:** `COMPANIES_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 company fields. include: type: object additionalProperties: {} default: {} description: >- Filter conditions to include. Supports special filters like `id`, `companyGroup`, `campaigns`, `leadsCount`, `isCompanyInCRM`, and any company field ID returned by the fields endpoint. Filter values should match the field data type returned by `GET /v1/companies/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`, `companyGroup` (company list IDs), `campaigns`, `leadsCount`, `isCompanyInCRM`, and any workspace scoring fields such as `icpScore` or `scoreBand` when those field IDs appear in the fields response. Unrecognized keys are rejected with a 400 rather than silently ignored. Use `GET /v1/companies/fields` (MCP tool `get_company_field_metadata`) to discover valid company field names for `fields`, `include`, `exclude`, and update payloads. 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/companies/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`, `companyGroup` (company list IDs), `campaigns`, `leadsCount`, `isCompanyInCRM`, and any workspace scoring fields such as `icpScore` or `scoreBand` when those field IDs appear in the fields response. Unrecognized keys are rejected with a 400 rather than silently ignored. Use `GET /v1/companies/fields` (MCP tool `get_company_field_metadata`) to discover valid company field names for `fields`, `include`, `exclude`, and update payloads. fields: anyOf: - type: string - type: array items: type: string description: >- Specific company fields to include in the response (comma-separated or array). Use `GET /v1/companies/fields` (MCP tool `get_company_field_metadata`) to discover valid company field names. examples: byListIdAndSize: summary: Filter companies by company list ID and employee range value: page: 1 pageSize: 25 search: analytics include: companyGroup: - 42 industry: - Software numberOfEmployees: - '50' - '500' byIdsAndLeadCount: summary: Filter companies by company IDs, lead count, and CRM presence value: page: 1 pageSize: 25 include: id: - 101 - 205 leadsCount: - '5' - '50' isCompanyInCRM: - true exclude: campaigns: - 88 scoringFieldExample: summary: >- Filter companies by a workspace-specific scoring field from the fields endpoint value: page: 1 pageSize: 25 include: companyGroup: - 42 scoreBand: - A withFields: summary: >- Include specific standard, AI variable, or scoring fields in the response (use the fields endpoint to discover valid IDs for this workspace) value: page: 1 pageSize: 25 fields: - industry - numberOfEmployees - accountPriority - icpScore include: companyGroup: - 42 responses: '200': description: Successful response with paginated companies content: application/json: schema: type: object properties: data: type: array items: type: object properties: id: type: number description: Unique identifier for the company appUrl: type: string format: uri description: Direct Enginy app URL for opening this company. name: type: - string - 'null' description: Company name domain: type: - string - 'null' description: Company website domain website: type: - string - 'null' description: Company website URL companyLinkedInUrl: type: - string - 'null' description: Company LinkedIn URL industry: type: - string - 'null' description: Industry sector rangeOfEmployees: type: - string - 'null' description: Range of employees (e.g., "11-50") numberOfEmployees: type: - number - 'null' description: Exact number of employees yearfounded: type: - string - 'null' description: Year the company was founded description: type: - string - 'null' description: Company description country: type: - string - 'null' description: Company country city: type: - string - 'null' description: Company city streetAddress: type: - string - 'null' description: Company street address phoneNumber: type: - string - 'null' description: Company phone number companyEmail: type: - string - 'null' description: Company email address revenueRange: type: - string - 'null' description: Company revenue range hiringOnLinkedIn: type: boolean description: Whether the company is actively hiring on LinkedIn openJobPositions: type: - number - 'null' description: Number of open job positions companyCRMId: type: - string - 'null' description: CRM company ID isCompanyInCRM: type: boolean description: Whether the company is synced with CRM contactsCount: type: number description: >- Number of contacts (leads) associated with this company. lastContactedAt: type: - string - 'null' format: date-time description: >- Date and time of the most recent outbound message sent to any contact at this company across all campaigns. Null when no contacts have 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 company was created updatedAt: type: string format: date-time description: Date and time when the company was last updated companyHeadcount: type: array items: type: object properties: employeeCount: type: - number - 'null' description: Number of employees in this department. threeMonthGrowth: type: - number - 'null' description: Three-month headcount growth percentage. sixMonthGrowth: type: - number - 'null' description: Six-month headcount growth percentage. oneYearGrowth: type: - number - 'null' description: One-year headcount growth percentage. department: type: string description: Department name. createdAt: type: string format: date-time description: >- Timestamp when this headcount snapshot was created. required: - employeeCount - threeMonthGrowth - sixMonthGrowth - oneYearGrowth - department - createdAt description: Employee headcount by department. required: - id - appUrl - name - domain - website - companyLinkedInUrl - industry - rangeOfEmployees - numberOfEmployees - yearfounded - description - country - city - streetAddress - phoneNumber - companyEmail - revenueRange - hiringOnLinkedIn - openJobPositions - companyCRMId - isCompanyInCRM - contactsCount - lastContactedAt - createdAt - updatedAt meta: type: object properties: page: type: number pageSize: type: number total: type: number required: - page - pageSize - total required: - data - meta security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ````