--- title: "Search Persons" method: POST path: "/v2/persons/search" tags: ["Persons"] --- # Search Persons `POST /v2/persons/search` | ⚠️ This endpoint is currently in BETA | |--| Search for Persons matching the given criteria. Accepts an optional combination of filters, sorts, and a search term. Omitting the body is equivalent to `GET /v2/persons` with default pagination. Requires the "Export All People directory" [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/persons/fields` to discover the available fields and their `valueType`. ### `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/persons/fields` to confirm which fields require an `attributeId`. ### Search The `search.term` is always matched against the person's first name, last name, and primary email address. 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. ## 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 - PersonPaged — PersonPaged model - `data` Person[], required — A page of Person results - `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 - CompaniesValue - `type` 'company-multi', required — The type of value - `data` CompanyData[], nullable, required — The values for many companies - `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 - `totalCount` integer — The total number of values for this field. When totalCount exceeds the length of data, additional values can be retrieved using the field values endpoint. - CompanyValue - `type` 'company', required — The type of value - `data` CompanyData, required - `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 - DateValue - `type` 'datetime', required — The type of value - `data` string, date-time, nullable, required — The value for a date - DropdownsValue - `type` 'dropdown-multi', required — The type of value - `data` Dropdown[], nullable, required — The value for many dropdown items - `dropdownOptionId` integer, required — Dropdown item's unique identifier - `text` string, required — Dropdown item text - `totalCount` integer — The total number of values for this field. When totalCount exceeds the length of data, additional values can be retrieved using the field values endpoint. - DropdownValue - `type` 'dropdown', required — The type of value - `data` Dropdown, required - `dropdownOptionId` integer, required — Dropdown item's unique identifier - `text` string, required — Dropdown item text - FloatsValue - `type` 'number-multi', required — The type of value - `data` number[], nullable, required — The value for many numbers - `totalCount` integer — The total number of values for this field. When totalCount exceeds the length of data, additional values can be retrieved using the field values endpoint. - FloatValue - `type` 'number', required — The type of value - `data` number, nullable, required — The value for a number - FormulaValue - `type` 'formula-number', required — The type of value - `data` FormulaNumber, required - `calculatedValue` number, nullable — Calculated value - InteractionValue - `type` 'interaction', required — The type of value - `data` union, required - ChatMessage - … - Email - … - Meeting - … - PhoneCall - … - LocationsValue - `type` 'location-multi', required — The type of value - `data` Location[], nullable, required — The values for many locations - `streetAddress` string, nullable, required — Street address - `city` string, nullable, required — City - `state` string, nullable, required — State - `country` string, nullable, required — Country - `continent` string, nullable, required — Continent - `totalCount` integer — The total number of values for this field. When totalCount exceeds the length of data, additional values can be retrieved using the field values endpoint. - LocationValue - `type` 'location', required — The type of value - `data` Location, required - `streetAddress` string, nullable, required — Street address - `city` string, nullable, required — City - `state` string, nullable, required — State - `country` string, nullable, required — Country - `continent` string, nullable, required — Continent - PersonsValue - `type` 'person-multi', required — The type of value - `data` PersonData[], nullable, required — The values for many persons - `id` integer, required — The persons's unique identifier - `firstName` string, nullable, 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 - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators. - `totalCount` integer — The total number of values for this field. When totalCount exceeds the length of data, additional values can be retrieved using the field values endpoint. - PersonValue - `type` 'person', required — The type of value - `data` PersonData, required - `id` integer, required — The persons's unique identifier - `firstName` string, nullable, 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 - `type` 'internal' | 'collaborator' | 'external', required — The person's type. `internal` - people who are users within your Affinity instance. `collaborator` - individuals outside of your company who have read-only access to specified Affinity list views and stay updated on your firm's activities. `external` - people who are not internal nor collaborators. - RankedDropdownValue - `type` 'ranked-dropdown', required — The type of value - `data` RankedDropdown, required - `dropdownOptionId` integer, required — Dropdown item's unique identifier - `text` string, required — Dropdown item text - `rank` integer, required — Dropdown item rank - `color` string, nullable, required — Dropdown item color - TextsValue - `type` 'filterable-text-multi', required — The type of value - `data` string[], nullable, required — The value for many strings - `totalCount` integer — The total number of values for this field. When totalCount exceeds the length of data, additional values can be retrieved using the field values endpoint. - TextValue - `type` 'filterable-text' | 'text', required — The type of value - `data` string, nullable, required — The value for a string - `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 - `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)