--- title: "Search List Entries" method: POST path: "/v2/lists/{listId}/list-entries/search" tags: ["Lists"] --- # Search List Entries `POST /v2/lists/{listId}/list-entries/search` | ⚠️ This endpoint is currently in BETA | |--| Search for List Entries on a List matching the given criteria. Accepts an optional combination of filters, sorts, and a search term. All fields in the request body are optional. Omitting the body entirely is equivalent to `GET /v2/lists/{listId}/list-entries` with default pagination. Requires the "Export data from Lists" [permission](/pages/external-api-v2/permissions). ### Field IDs Field IDs used in `filters`, `sorts`, and `search.fieldIds` follow the formats described in [Working with Field Data](/pages/data-model/working-with-field-data). Use `GET /v2/lists/{listId}/fields?includes=filterability` to discover which fields are filterable and what operators each supports. Use `GET /v2/lists/{listId}/fields?includes=sortability` for sortable fields. ### `attributeId` Some fields require an `attributeId` to specify which aspect to filter or sort on. The following relationship intelligence fields all use `attributeId: "date-of-activity"`: `last-email`, `first-email`, `last-contact`, `last-event`, `first-event`, `next-event`. Use `GET /v2/lists/{listId}/fields?includes=filterability` to confirm which fields require an `attributeId`. ### Search The `search.term` is always matched against the entity's name and primary identifier: company name and primary domain (company lists), person first name, last name, and primary email address (person lists), or opportunity name (opportunity lists). Providing `search.fieldIds` extends the search to those additional fields; it does not restrict matching to only those fields. Fields with a `valueType` of `datetime` are not searchable and are silently ignored if included in `search.fieldIds`. ### Limits - **Items per filter group** (filters or nested groups): 50 - **Values per filter** (e.g. options in `is-any-of`): 100 - **Sort criteria**: 5 - **Search term minimum length**: 3 characters - **Results per page**: 100 ### Pagination Uses cursor-based pagination. ## Path parameters - `listId` integer, required ## Query parameters - `fieldIds` string[] - `fieldTypes` string[] - `cursor` string - `limit` integer - `totalCount` boolean ## Request body - SearchCriteria — Search criteria for filtering, sorting, and searching. All fields are optional — omitting the body returns all results with default pagination. - `filters` FilterGroup — A logical group of filters combined with AND or OR. Groups can be nested to build complex filter trees. Each group may contain up to 50 items. Items can be individual filters or nested filter groups. - `operator` 'and' | 'or', required — The logical operator applied to all filters in this group - `filters` union[], required — A list of filters or nested filter groups. - union - union — A filter applied to a single field value. The `valueType` determines which filter variant applies and what operators and `value` shapes are valid. Each filter requires `fieldId`, `valueType`, and `operator`. The `value` field is required for most operators and absent for `is-empty` and `is-not-empty`. Some fields also require an `attributeId` — use the relevant fields endpoint for your resource type to discover available fields, their `valueType`, supported operators, and required `attributeId` values. - union — Filter for single-company fields - CompanyFilterMultiValues — Filter for single-company fields matching against one or more companies - … - CompanyFilterNoValue — Filter for single-company fields based on presence or absence of a value - … - union — Filter for multi-company fields - CompaniesFilterMultiValues — Filter for multi-company fields matching against one or more companies - … - CompaniesFilterNoValue — Filter for multi-company fields based on presence or absence of a value - … - union — Filter for single-person fields - PersonFilterMultiValues — Filter for single-person fields matching against one or more persons - … - PersonFilterNoValue — Filter for single-person fields based on presence or absence of a value - … - union — Filter for multi-person fields - PersonsFilterMultiValues — Filter for multi-person fields matching against one or more persons - … - PersonsFilterNoValue — Filter for multi-person fields based on presence or absence of a value - … - union — Filter for dropdown fields - DropdownFilterMultiValues — Filter for dropdown fields matching against one or more dropdown options - … - DropdownFilterNoValue — Filter for dropdown fields based on presence or absence of a value - … - union — Filter for multi-dropdown fields - DropdownsFilterMultiValues — Filter for multi-dropdown fields matching against one or more dropdown options - … - DropdownsFilterNoValue — Filter for multi-dropdown fields based on presence or absence of a value - … - union — Filter for ranked-dropdown fields - RankedDropdownFilterMultiValues — Filter for ranked-dropdown fields matching against one or more ranked dropdown options - … - RankedDropdownFilterNoValue — Filter for ranked-dropdown fields based on presence or absence of a value - … - union — Filter for date fields - DateFilterOneValue — Filter for date fields relative to or matching a single date - … - DateFilterRange — Filter for date fields within an absolute date range (inclusive) - … - DateFilterRelative — Filter for date fields within a relative date window - … - DateFilterRelativeDate — Filter for date fields using a single relative duration threshold - … - DateFilterNoValue — Filter for date fields based on presence or absence of a value - … - union — Filter for number fields - NumberFilterOneValue — Filter for number fields comparing against a single numeric value - … - NumberFilterRange — Filter for number fields within a numeric range (inclusive) - … - NumberFilterNoValue — Filter for number fields based on presence or absence of a value - … - union — Filter for filterable-text fields (single-value structured text with predefined options) - FilterableTextFilterMultiValues — Filter for filterable-text fields matching against one or more text values - … - FilterableTextFilterNoValue — Filter for filterable-text fields based on presence or absence of a value - … - union — Filter for filterable-text-multi fields (multi-value structured text with predefined options) - FilterableTextsFilterMultiValues — Filter for filterable-text-multi fields matching against one or more text values - … - FilterableTextsFilterNoValue — Filter for filterable-text-multi fields based on presence or absence of a value - … - union — Filter for free-text fields - TextFilterOneValue — Filter for free-text fields using a string match against a single value - … - TextFilterNoValue — Filter for free-text fields based on presence or absence of a value - … - union — Filter for single-location fields - LocationFilterMultiValues — Filter for single-location fields matching against one or more location values - … - LocationFilterNoValue — Filter for single-location fields based on presence or absence of a value - … - union — Filter for multi-location fields - LocationsFilterMultiValues — Filter for multi-location fields matching against one or more location values - … - LocationsFilterNoValue — Filter for multi-location fields based on presence or absence of a value - … - FilterGroup — recursive - `sorts` SearchSort[] — One or more sort criteria, applied in order. Supports up to 5 sort items. Use the relevant fields endpoint for your resource type to discover sortable fields. - `fieldId` string, required — The ID of the field to sort on - `attributeId` string — The ID of the attribute to sort on. Required for some fields such as relationship intelligence fields. Use the relevant fields endpoint for your resource type to discover which fields require an `attributeId` and what values are valid. - `direction` 'asc' | 'desc', required — The sort direction - `search` SearchTerm — A single keyword or phrase to match against field values. Multiple terms or comma-separated values are not supported; use a single search string. - `term` string, required — The text to search for. Minimum 3 characters. - `fieldIds` string[] — The IDs of additional fields to match the term against, extending the default identity search. Use the relevant fields endpoint for your resource type to discover available field IDs. Supports up to 100 field IDs. Fields with a `valueType` of `datetime` are not searchable and are silently ignored if included. ## Response `201` Created - ListEntryWithEntityPaged — ListEntryWithEntityPaged model - `data` ListEntryWithEntity[], nullable, required — A page of ListEntryWithEntity results - union - CompanyListEntry - `id` integer, required — The list entry's unique identifier - `type` 'company', required — The entity type for this list entry - `listId` integer, required — The ID of the list that this list entry belongs to - `createdAt` string, date-time, required — The date that the list entry was created - `creatorId` integer, nullable, required — The ID of the user that created this list entry - `entity` Company, required — Company model - `id` integer, required — The company's unique identifier - `name` string, required — The company's name - `domain` string, hostname, nullable, required — The company's primary domain - `domains` string[], required — All of the company's domains - `isGlobal` boolean, required — Whether or not the company is tenant specific - `fields` Field[] — The fields associated with the company - `id` string, required — The field's unique identifier - `name` string, required — The field's name - `type` 'enriched' | 'global' | 'list' | 'relationship-intelligence' | 'hidden', required — The field's category. `hidden` is a redaction state rather than a category: it signals a field on a restricted opportunity the caller cannot manage, whose value is masked. - `enrichmentSource` 'affinity-data' | 'dealroom' | 'eventbrite' | 'mailchimp' | 'null', nullable, required — The source of the data in this Field (if it is enriched) - `value` union, required - … - OpportunityListEntry - `id` integer, required — The list entry's unique identifier - `type` 'opportunity', required — The entity type for this list entry - `listId` integer, required — The ID of the list that this list entry belongs to - `createdAt` string, date-time, required — The date that the list entry was created - `creatorId` integer, nullable, required — The ID of the user that created this list entry - `entity` OpportunityWithFields, required — Opportunity model including the opportunity's fields. - `id` integer, required — The unique identifier for the opportunity - `name` string, required — The name of the opportunity. - `listId` integer, required — The ID of the list that the opportunity belongs to - `fields` Field[] — The fields associated with the opportunity. Empty for a redacted opportunity. - `id` string, required — The field's unique identifier - `name` string, required — The field's name - `type` 'enriched' | 'global' | 'list' | 'relationship-intelligence' | 'hidden', required — The field's category. `hidden` is a redaction state rather than a category: it signals a field on a restricted opportunity the caller cannot manage, whose value is masked. - `enrichmentSource` 'affinity-data' | 'dealroom' | 'eventbrite' | 'mailchimp' | 'null', nullable, required — The source of the data in this Field (if it is enriched) - `value` union, required - … - `isRestricted` boolean, required — Whether the opportunity is restricted. `false` for customers without the Restricted Opportunities feature enabled. - `isRedacted` boolean, required — Whether the response is redacted because the requesting user does not have access to sensitive details of this restricted opportunity. When `true`, `fields` is empty. Always `false` when `isRestricted` is `false`. - PersonListEntry - `id` integer, required — The list entry's unique identifier - `type` 'person', required — The entity type for this list entry - `listId` integer, required — The ID of the list that this list entry belongs to - `createdAt` string, date-time, required — The date that the list entry was created - `creatorId` integer, nullable, required — The ID of the user that created this list entry - `entity` Person, required — Person model - `id` integer, required — The persons's unique identifier - `firstName` string, required — The person's first name - `lastName` string, nullable, required — The person's last name - `primaryEmailAddress` string, email, nullable, required — The person's primary email address - `emailAddresses` string[], required — All of the person's email addresses - `type` 'internal' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `external` - people who are not internal. - `fields` Field[] — The fields associated with the person - `id` string, required — The field's unique identifier - `name` string, required — The field's name - `type` 'enriched' | 'global' | 'list' | 'relationship-intelligence' | 'hidden', required — The field's category. `hidden` is a redaction state rather than a category: it signals a field on a restricted opportunity the caller cannot manage, whose value is masked. - `enrichmentSource` 'affinity-data' | 'dealroom' | 'eventbrite' | 'mailchimp' | 'null', nullable, required — The source of the data in this Field (if it is enriched) - `value` union, required - … - `pagination` Pagination, required - `prevUrl` string, uri, nullable — URL for the previous page - `nextUrl` string, uri, nullable — URL for the next page ## Other responses - `400` — Bad Request - `403` — Forbidden - `404` — Not Found - `default` — Errors --- [API](https://skmtc.net/affinity/apis/affinity-api-v2.md) · [All operations](https://skmtc.net/affinity/apis/affinity-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/affinity/affinity-api-v2/revisions/4c2891c31b7f/schema)