# Search Socotra's search allows you to find the following entities quickly and easily: * Policies * Quotes * Accounts * Contacts * Diaries * First Notice of Loss ("FNOL") * Payments Overview [#overview] You can search against locators, static data, and data extensions of type `string`. For entities supporting [numbering](/configuration/general-topics/entity-numbering), you can also search by number. If there is a match with some degree of relevancy, the corresponding entity will be returned for that match. Results are ordered by relevancy score, from highest to lowest. Relevancy scores are boosted for matches on locators, static data, and entity numbers, helping to ensure that such results emerge towards the top of the results. Example [#example] If you have an account configured with a [data extension](/configuration/data-extensions/overview) field `lastName`, and there is at least one account with last name "Swerski" in your set of accounts, a search query for `Swerski` will return at least one result: the account record for "Swerski", with a high relative score. Request [#request] `POST` request body: ```json { "searchString": "Swerski" } ``` Response [#response] ```json { "searchToken": "eyJzZWFyY2hSZXF1ZXN0Ijp7InNlYXJjaFN0cmluZyI6IlN3ZXJza2kifX0=", "offset": 0, "count": 10, "results": [ { "score": 2.0, "searchEntityType": "account", "searchEntityLocator": "01JSH3DEPHHTRE6SQE8F9JH0J3", "searchSummary": { "account_number": "A223455", "data": { "firstName": "Bill", "lastName": "Swerski" }, "name": "ConsumerAccount", "state": "validated" }, "highlights": [ "Score:2.0 ,Document: 01JSH3DEPHHTRE6SQE8F9JH0J3,Highlight: {entity.data.lastName=[Swerski]}" ] }, { "score": 0.85714287, "searchEntityType": "account", "searchEntityLocator": "01JSH3E88RHZJTTVJNQX9XCAGK", "searchSummary": { "account_number": "B229455", "data": { "firstName": "Bill", "lastName": "Swersky" }, "name": "ConsumerAccount", "state": "validated" }, "highlights": [ "Score:0.85714287 ,Document: 01JSH3E88RHZJTTVJNQX9XCAGK,Highlight: {entity.data.lastName=[Swersky]}" ] } ] } ``` A similar name, "Swersky", appears in the results, but with lower relevance than the more exact match on "Swerski". An exact match request with "Swerski" wrapped in (escaped) quotes would only return the "Swerski" account. Read on for details about search behavior and search string syntax. Requests [#requests] Requests can be sent as a single `searchString` or as a `searchTerm` array. See the [API reference](/api/search) for details. Search String Syntax [#search-string-syntax] A search request comprises search terms - an array of `searchTerm` items - and can be expressed as a `searchString`. `searchString` syntax allows you to express a complete query in a single string, such as one passed through a typical search form box. A search string follows these rules: * A sequence one or more `searchTerm` strings, separated by whitespace. * Each `searchTerm` string has the following form: * Form: `[+|-][fieldName:]string[*]` * The `fieldName` slug determines whether the match should be against a specific field name or any field. * The `fieldName` can be qualified by the full path of the element to which it belongs, which allows for greater specificity in your query. For example, a top-level `lastName` data extension `string` on an account can be searched like this: `+data.lastName:Swerski`, while a `firstName` data extension on an exposure "insured" under some product can be searched as `+insuredQuote.firstName:Veronica` (for quotes) or `+insuredPolicy.firstName:Veronica` (for policies). * Term relevance scoring: * If the term is prefixed with a `+`, the term is required for search result relevance. * If the term is prefixed with a `-`, the term must be excluded for search result relevance. * Absence of `+` or `-` before a term is interpreted as a suggestion: the presence of the term increases the relevance score, but does not require that the term be present or absent from a match candidate. * The default match behavior is fuzzy. * Appending `*` to the term sets matching to `startsWith`. * Enclosing the term in double quotes sets matching to `exact`. Searches with spaces cannot be fuzzy searches. * Only `exact` matching is case-sensitive. Entity Numbering [#entity-numbering] [Entity numbers](/configuration/general-topics/entity-numbering) have dedicated indexing to provide improved search performance for these key identifiers. The searchable entities that support numbering at this time are: * Accounts * Quotes * Policies * FNOLs To match against a specific [entity number](/configuration/general-topics/entity-numbering) using `fieldName`, the `fieldName` must be set to `entity_number`, regardless of the entity type. For example, a `policyNumber` or `quoteNumber` can be searched like this: `entity_number:A00000-PA-SD`. Entity numbers may contain any number of non-alphanumeric symbols. To make searching for these numbers more flexible, all such symbols are ignored during `fuzzy` or `startsWith` searches. This enables users to find entities whether or not symbols are included in their search request. For example, `A00000-PA-SD` can be searched as `A00000-PA-SD`, `A00000PA-SD`, `A00000-PASD` or `A00000PASD`. Relevancy scores are boosted for matches on entity numbers. `POST` request body example: ```json { "searchString": "entity_number:A00000-PA-SD" } ``` Filtering [#filtering] You may restrict results to a creation time range using the optional `endCreationTime` or `startCreationTime` parameters. Responses [#responses] The provides a list of `results`, along with properties to assist in paging through results. You can fetch up to 100 results at a time, and use the `count`, `offset`, and `searchToken` values to control pagination. If no `count` is set for the initial search request, it will be set to `100`. The `searchToken` should be used in subsequent `GET` requests to page through the results, with `count` serving as the number of results to be returned in the page and `offset` as the starting index (beginning at `0`) in the result list. For example, if you perform a search with a total of 70 results, and want to page through 25 results at a time, you can do it with three requests, all setting `count` to `25`: 1. The initial query 2. A second query, along with the `searchToken` and `offset` as `25` 3. A final query , along with the `searchToken` and `offset` as `50` You'll know that you have exhausted the result set when the length of the result list is less than `count`. If there are no results beginning at some `offset` index, the service will return an empty result list. You can set the `count` to another value when fetching results; following the example above, if you decided you wanted all the results in a single response, just provide the `searchToken` with `count` at least `70`. A provided `count` greater than `100` will be set to `100`. Relevance [#relevance] The `highlights` and `score` properties provide additional context about the match. In `highlights` you will find one or more excerpts from text that matched the query, while `score` indicates the relative numerical value assigned for ranking. You'll see very high `score` values for certain cases, such as exact matches on locator values. Search Summary [#search-summary] The `searchSummary` object serves as a digest about the entity, reducing the need for subsequent data fetches from the API in order to understand which entity is being referred to, or to display the search result in an effective way. The contents of `searchSummary` depends on the result entity type: * Quotes and policies will have all static data fields in a `static` property. * Quotes will also have a `state` property. * All other searchable entities will include all string-type data extension field values in the `data` property. "``\_number" will also appear as a search summary property if the entity supports numbering, and a number is assigned. The account results shown in this guide include `account_number`, for example, even though any search request for that number using `fieldName` must refer to `entity_number` rather than `account_number`. Field Augmentation [#field-augmentation] You can augment the `searchSummary` by supplying string values in the `fields` array of the . Any field (data extension) whose name matches one of the strings in `fields` will appear as an entry in the `searchSummary` map, with the full field name and dot-delimited path as the key. For example, a search request with `"fields": ["model", "vin"]` could yield a `searchSummary` with entries like this: ```json { // ..., "searchSummary": { "entity1.elements1.PersonalVehicleQuote.VIN": "4T1R11AK5MU610710", "entity1.elements1.PersonalVehicleQuote.model": "Camry", "entity1.elements2.PersonalVehicleQuote.VIN": "WAUV2AF20KN111732", "entity1.elements2.PersonalVehicleQuote.model": "A7", "state": "draft" } // ... } ``` Sample Responses [#sample-responses] A for a "ConsumerAccount" account (search query was simply "Evans"): ```json { "score": 2.0, "searchEntityType": "account", "searchEntityLocator": "01JSH42HR5MYXAZQSCR13WNJ5P", "searchSummary": { "account_number": "C229458", "data": { "firstName": "Bill", "lastName": "Evans" }, "name": "ConsumerAccount", "state": "validated" }, "highlights": [ "Score:2.0 ,Document: 01JSH42HR5MYXAZQSCR13WNJ5P,Highlight: {entity.data.lastName=[Evans]}" ] } ``` A for a quote result when searched by locator -- note the high relevancy score, since the search service boosts relevancy for exact matches on locators: ```json { "score": 101.0, "searchEntityType": "account", "searchEntityLocator": "01JSH42HR5MYXAZQSCR13WNJ5P", "searchSummary": { "account_number": "C229458", "data": { "firstName": "Bill", "lastName": "Evans" }, "name": "ConsumerAccount", "state": "validated" }, "highlights": [ "Score:101.0 ,Document: 01JSH42HR5MYXAZQSCR13WNJ5P,Highlight: {entity.locator.keyword=[01JSH42HR5MYXAZQSCR13WNJ5P]}" ] } ``` Configuration [#configuration] Search is enabled by default, indexing locators, some entity numbers, and data extension fields of type `string`. String field indexing includes data fields contained within [Custom Data Types](/configuration/data-extensions/custom-data-types) and in static data. Locator indexing makes it possible to search for quotes, policies, and accounts by locator, along with elements by locator or static locator. Entity number indexing makes it possible to search for quotes, policies, accounts, and FNOLs by entity number. You may use the `defaultSearchable` and `searchable` configuration properties to more precisely control which string fields are indexed for search. `defaultSearchable` is available at the top level of the configuration, in addition to configuration for accounts, products, and elements. When `defaultSearchable` is `true`, all string fields at that level and below are indexed. When `defaultSearchable` is `false`, then a string field must have `searchable` set to `true` in order to be indexed for search. For a given field, the nearest `defaultSearchable` value when going up the configuration hierarchy applies. While Socotra allows you to create draft entities with fields not specified in the configuration, the search service will only index fields on draft entities that are actually present in the configuration. See Also [#see-also] * [Search API reference](/api/search)