> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Search companies > Advanced company search with filtering, sorting, and custom attribute filters. **Filters**: keywords (name/domain/LinkedIn), exact domain, exact linkedin_url, is_client, company_status_ids, owner_ids, relationships, list_ids, job_id, company_ids. **Custom attribute filters**: `select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, `team_member_attribute_filters`. Get attribute IDs and tag IDs from GET /v1/custom-fields/companies. **Sorting**: Pass `sort_by` with one of: `name`, `domain`, `status` (client status stage order), `date_of_last_engagement`, `created_at` (default), or `custom_` for any custom field. Pair with `sort_order` (`asc` or `desc`, default `desc`). **Include control**: Pass `include: ["custom_fields"]` to embed custom field values in each result. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/companies/search openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/companies/search: post: tags: - Companies summary: Search companies description: >- Advanced company search with filtering, sorting, and custom attribute filters. **Filters**: keywords (name/domain/LinkedIn), exact domain, exact linkedin_url, is_client, company_status_ids, owner_ids, relationships, list_ids, job_id, company_ids. **Custom attribute filters**: `select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, `team_member_attribute_filters`. Get attribute IDs and tag IDs from GET /v1/custom-fields/companies. **Sorting**: Pass `sort_by` with one of: `name`, `domain`, `status` (client status stage order), `date_of_last_engagement`, `created_at` (default), or `custom_` for any custom field. Pair with `sort_order` (`asc` or `desc`, default `desc`). **Include control**: Pass `include: ["custom_fields"]` to embed custom field values in each result. operationId: searchCompanies requestBody: content: application/json: schema: $ref: '#/components/schemas/CompaniesSearchBody' responses: '200': description: Companies found content: application/json: schema: $ref: '#/components/schemas/CompaniesSearchResponse' example: success: true data: - id: 456e7890-e12b-34d5-a678-901234567890 name: Acme Corp domain: acme.com linkedin_url: https://www.linkedin.com/company/acme is_client: true do_not_contact: true do_not_contact_metadata: reason: Active client — protect from sourcing do_not_contact_added_by: 234e5678-e90a-12b3-c456-789012345678 date_added: '2024-06-01T09:00:00Z' last_updated_at: '2024-06-15T14:30:00Z' last_updated_by: 234e5678-e90a-12b3-c456-789012345678 expiration_date: '2024-09-15T00:00:00Z' created_at: '2024-01-05T10:00:00Z' client_status: id: 789e0123-e45f-67a8-b901-234567890123 name: Active date_of_last_engagement: '2024-06-15T14:30:00Z' enriched_company: id: ec123456-7890-abcd-ef01-234567890abc name: Acme Corp domain: acme.com linkedin_url: https://www.linkedin.com/company/acme job_target_companies: [] owners: - id: 234e5678-e90a-12b3-c456-789012345678 first_name: Jane last_name: Smith relationships: [] custom_fields: - attribute_id: e5f6a7b8-c9d0-1234-efab-567890123456 attribute_name: Industry data_type: single-select value: null tag: id: f6a7b8c9-d0e1-2345-fabc-678901234567 name: Technology team_member: null meta: total: 42 offset: 0 limit: 100 '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: CompaniesSearchBody: type: object properties: offset: type: integer minimum: 0 default: 0 description: Records to skip for pagination. Defaults to 0. limit: type: integer minimum: 1 maximum: 100 default: 100 description: Max records to return (1–100). Defaults to 100. sort_by: type: string description: >- Column to sort by. Accepted values: - `name` — company name (alphabetical) - `domain` — website domain (alphabetical) - `status` — client status (by stage order) - `date_of_last_engagement` — most recent engagement date - `created_at` — creation timestamp (default) - `custom_` — any custom attribute UUID prefixed with `custom_` (e.g. `custom_e5f6a7b8-c9d0-1234-efab-567890123456`). Sorts by the attribute's decimal, date, string, or tag value. sort_order: type: string enum: - asc - desc default: desc description: Sort direction. Defaults to desc (newest first). keywords: type: array items: type: string description: Full-text search across company name, domain, and LinkedIn URL. domain: type: string description: Filter by exact website domain (e.g. "acme.com"). linkedin_url: type: string description: Filter by exact LinkedIn company URL. is_client: type: boolean description: >- Filter by client status. true = clients only, false = non-clients, omit = all. job_id: type: string format: uuid description: Filter to target companies of this job. list_id: type: string format: uuid description: Filter to companies belonging to this list. company_ids: type: array items: type: string format: uuid description: Pre-filter to a specific set of company IDs. company_status_ids_included: type: array items: type: string format: uuid description: Include only companies with these client status IDs. company_status_ids_excluded: type: array items: type: string format: uuid description: Exclude companies with these client status IDs. owner_ids_included: type: array items: type: string format: uuid description: >- Include only companies owned by these team members. Get IDs from GET /v1/team-members. owner_ids_excluded: type: array items: type: string format: uuid description: Exclude companies owned by these team members. relationships_included: type: array items: type: object properties: company_id: type: string format: uuid description: UUID of the related company. relationship_type: type: string description: >- Relationship type key. Omit to match any relationship with this company. required: - company_id description: >- Include only companies with a relationship to any of these companies. relationships_excluded: type: array items: type: object properties: company_id: type: string format: uuid description: UUID of the related company. relationship_type: type: string description: >- Relationship type key. Omit to match any relationship with this company. required: - company_id description: Exclude companies with a relationship to these companies. list_ids_included: type: array items: type: string format: uuid description: Include companies belonging to any of these lists. list_ids_excluded: type: array items: type: string format: uuid description: Exclude companies belonging to any of these lists. job_association: type: string enum: - has_jobs - no_jobs description: >- Filter by job association. "has_jobs" returns companies with at least one non-deleted job. "no_jobs" returns companies with no jobs. job_status_filter: type: string enum: - active_or_archived - active_only - archived_only description: >- When job_association is "has_jobs", further filter by job status. "active_or_archived" (default) matches any non-deleted job. "active_only" matches companies with at least one active (non-archived) job. "archived_only" matches companies that only have archived jobs (no active ones). select_attribute_filters: type: array items: type: object properties: attribute_id: type: string format: uuid description: >- Attribute definition UUID. Get from GET /v1/custom-fields/{entity}. values: type: array items: type: string default: [] description: >- Tag option UUIDs to include. Get tag IDs from the attribute's tags array in custom field definitions. excluded_values: type: array items: type: string default: [] description: Tag option UUIDs to exclude. require_all: type: boolean default: false description: >- When true, record must have ALL specified tags (AND logic). When false, any tag matches (OR logic). include_empty: type: boolean default: false description: >- When true, also include records with no value set for this attribute. required: - attribute_id description: >- Filter by select/multi-select custom fields. Get attribute_id and tag IDs from GET /v1/custom-fields/companies. numeric_attribute_filters: type: array items: type: object properties: attribute_id: type: string format: uuid description: >- Attribute definition UUID (integer or decimal type). Get from GET /v1/custom-fields/{entity}. min: type: - number - 'null' description: Minimum value (inclusive). Null for no lower bound. max: type: - number - 'null' description: Maximum value (inclusive). Null for no upper bound. include_empty: type: boolean default: false description: When true, also include records with no value set. required: - attribute_id description: >- Filter by numeric custom fields (min/max range). Get attribute_id from GET /v1/custom-fields/companies. date_attribute_filters: type: array items: type: object properties: attribute_id: type: string format: uuid description: >- Attribute definition UUID (date type). Get from GET /v1/custom-fields/{entity}. start_date: type: - string - 'null' description: Start of date range (ISO 8601). Null for no lower bound. end_date: type: - string - 'null' description: End of date range (ISO 8601). Null for no upper bound. include_empty: type: boolean default: false description: When true, also include records with no value set. required: - attribute_id description: >- Filter by date custom fields (date range). Get attribute_id from GET /v1/custom-fields/companies. team_member_attribute_filters: type: array items: type: object properties: attribute_id: type: string format: uuid description: >- Attribute definition UUID (multi-team-member type). Get from GET /v1/custom-fields/{entity}. values: type: array items: type: string format: uuid default: [] description: >- Team member UUIDs to include. Get IDs from GET /v1/team-members. excluded_values: type: array items: type: string format: uuid default: [] description: Team member UUIDs to exclude. require_all: type: boolean default: false description: >- When true, record must have ALL specified team members (AND logic). include_empty: type: boolean default: false description: >- When true, also include records with no team member assigned for this attribute. required: - attribute_id description: >- Filter by team-member custom fields. Get attribute_id from GET /v1/custom-fields/companies. include: type: array items: type: string enum: - custom_fields description: >- Extra sections to embed. Values: custom_fields. Omit for base fields only. CompaniesSearchResponse: type: object properties: success: type: boolean enum: - true data: type: array items: $ref: '#/components/schemas/CompanySearchItem' meta: type: object properties: total: type: number description: Total matching records across all pages. offset: type: number description: Current pagination offset. limit: type: number description: Page size used for this request. required: - total - offset - limit required: - success - data - meta CompanySearchItem: type: object properties: id: type: string description: Company UUID. name: type: string description: Company name. domain: type: - string - 'null' description: Website domain. linkedin_url: type: - string - 'null' description: LinkedIn company page URL. is_client: type: boolean description: True if company is a client. do_not_contact: type: boolean description: True if flagged do-not-contact. do_not_contact_metadata: type: - object - 'null' additionalProperties: {} description: Do-not-contact metadata (reason, set_by, etc.). created_at: type: string description: ISO 8601 creation timestamp. client_status: type: - object - 'null' properties: id: type: string description: Client status UUID. name: type: string description: >- Client status label (e.g. "Active", "Prospect", "Former Client"). required: - id - name description: >- Client lifecycle status with id and name. Null if no status assigned. date_of_last_engagement: type: - string - 'null' description: ISO 8601 timestamp of the most recent engagement. enriched_company: type: - object - 'null' properties: id: type: string description: Enriched company UUID. name: type: string description: Enriched company name. domain: type: - string - 'null' description: Enriched domain. linkedin_url: type: - string - 'null' description: Enriched LinkedIn URL. required: - id - name - domain - linkedin_url description: Enriched company data snapshot. job_target_companies: type: array items: type: object properties: job_id: type: string description: Job UUID. organization_company_id: type: string description: Company UUID. notes: type: - string - 'null' description: Target company notes. required: - job_id - organization_company_id - notes description: >- Job target company associations (populated when job_id filter is used). owners: type: array items: type: object properties: id: type: string description: Team member UUID. first_name: type: - string - 'null' description: First name. last_name: type: - string - 'null' description: Last name. required: - id - first_name - last_name description: Team members who own this company. relationships: type: array items: type: object properties: relation_type: type: string description: Relationship type key. relation_type_name: type: string description: Relationship type display name. related_company_id: type: string description: Related company UUID. related_company_name: type: string description: Related company name. note: type: - string - 'null' description: Optional note. required: - relation_type - relation_type_name - related_company_id - related_company_name - note description: >- Company relationships (populated when relationship filter is active). custom_fields: type: array items: $ref: '#/components/schemas/CustomFieldValue' description: Custom field values. Included when include contains "custom_fields". required: - id - name - domain - linkedin_url - is_client - do_not_contact - do_not_contact_metadata - created_at - client_status - date_of_last_engagement - enriched_company - job_target_companies - owners - relationships CustomFieldValue: type: object properties: attribute_id: type: string format: uuid description: >- Attribute definition UUID. Get definitions from GET /v1/custom-fields/{entity}. attribute_name: type: string description: Attribute display name. data_type: type: string enum: - string - integer - decimal - multi-select - single-select - boolean - date - multi-team-member - url description: Attribute data type. Determines which value field contains the data. job_id: type: - string - 'null' format: uuid description: >- Job UUID this attribute is scoped to. Null for global person-level attributes. Present when this custom field is specific to a job (candidate-level field). list_id: type: - string - 'null' format: uuid description: >- List UUID this attribute is scoped to. Null for global person-level attributes. value: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: 'null' description: >- Scalar value for string, integer, decimal, date, url, boolean types. Null for select/team-member types. tag: type: - object - 'null' properties: id: type: string format: uuid description: Tag option UUID. name: type: string description: Tag display name. required: - id - name description: >- Tag value for single-select and multi-select types. Null for other types. For multi-select, one CustomFieldValue row per tag. team_member: type: - object - 'null' properties: id: type: string format: uuid description: Team member UUID. name: type: - string - 'null' description: Team member full name. required: - id - name description: >- Team member value for multi-team-member type. Null for other types. One CustomFieldValue row per team member. required: - attribute_id - attribute_name - data_type - job_id - list_id - value - tag - team_member securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````