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

You can search against locators, static data, and data extensions of type string. For entities supporting 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

If you have an account configured with a data extension 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

POST request body:

{
    "searchString":"Swerski"
}

Response

{
    "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=[<em>Swerski</em>]}"
            ]
        },
        {
            "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=[<em>Swersky</em>]}"
            ]
        }
    ]
}

Note

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 can be sent as a single searchString or as a searchTerm array. See the API reference for details.

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 numbers 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 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:

{
    "searchString": "entity_number:A00000-PA-SD"
}

Filtering

You may restrict results to a creation time range using the optional endCreationTime or startCreationTime SearchRequest parameters.

Responses

The SearchServiceResponse provides a list of SearchResultResponse 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:

The initial query
A second query, along with the searchToken and offset as 25
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

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

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.

“<entity>_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

You can augment the searchSummary by supplying string values in the fields array of the SearchRequest. 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:

{
    // ...,
    "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

A SearchResultResponse for a “ConsumerAccount” account (search query was simply “Evans”):

{
    "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=[<em>Evans</em>]}"
    ]
}

A SearchResultResponse for a quote result when searched by locator – note the high relevancy score, since the search service boosts relevancy for exact matches on locators:

{
    "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=[<em>01JSH42HR5MYXAZQSCR13WNJ5P</em>]}"
    ]
}

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 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.