Skip to content
Search! & Match! API


Search Request🔗


The SearchRequest as provided by the client. It allows to specify a query as

  1. a query string,
  2. a list of parsed query parts (from previous queries).

When a query (user-typed or generated) is sent to the Search web service, it is interpreted by Search! and returned as a list of query parts. These can be visualized to the user and allow for alteration, such as removing parts from the list. On subsequent calls to the Search web service, the list of parsed query parts is supplied in place of the query string.

When a request contains query parts (from the previous query) together with new query, the query parts resulting from interpretation of the new query are merged with the old query. Merging will automatically apply AND/OR mode as configured for the respective field if a single new query constraint is submitted.

Furthermore, the SearchRequest provides a number of options to parameterize the search results. All fields are optional, undefined values receive appropriate defaults, as configured in the search environment.

In general, only the query string gets interpreted (spelling correction, location resolving, synonym expansion), the query parts are not sent to the interpretation pipeline again, since they are supposed to come from a previous search request, and hence are already interpreted. However, there are a few cases in which query parts should at least get expanded by synonyms, and the complete synonym map for the entire request (query + query parts) needs to be rebuild. For this purpose the synonym expansion mode can be set to one of the following 3 options:

  • QUERY: build the synonym map from the query only, expand the query. This is the default option.
  • QUERY_AND_QUERYPARTS: build synonym map from both query and query parts, expand the query, prune and expand the query parts.
  • QUERY_AND_SYNONYMMAP: build synonym map from both query and query parts, expand the query, only prune the query parts.


Parameter Name Type Description default
query string user typed keyword query (see query language description). It may be joined with the queryParts if it is a single OR-combination part that can be joined. empty
queryParts list of QueryPart list of query parts coming from parsing a previous query. empty
hiddenQueryParts list of QueryPart list of query parts treated as hidden parts (not returned and highlighted). empty
resultFields list of string optional customization of the fields to be included in the results. If it consists of a single wildcard field marked by "*" (star) then all available fields will be returned. If empty then the default result field set will be returned. Remark: Reducing the returned fields this way, will not in general improve performance, since Search is optimized to return the standard configured field set. It is not possible to request system fields such as 'roles' or nested sub-fields. empty
searchAfter list of string Used for pagination within Elastic Search Searcher (ignored for external searchers). Represents the sort values of the last item from the previous page. Must contain exactly the searchAfter of Search Result returned from the previous page query. empty
resultOffset integer the result item offset used for pagination. For example, a value of 20 will skip the top 20 results and return the subsequent results starting with result 21. resultOffset is ignored if searchAfter is set. resultOffset+pagesize cannot be more than 10000. 0
pageSize integer optional parameter to specify the number of result items (max 1500). Only use a high number in case you need a list of results for use in follow-up actions. Do not use a high number when presenting results in a user interface. Therefore, pageSize is limited to 100 when used in combination with pagination parameters (searchAfter or resultOffset). And when pageSize is larger than 100, facet counts and search term highlighting are not provided (suppressFacetCounts and suppressHighlighting are implicitly set to true). If pageSize is not provided, the pre-configured page size of the searcher will be used. The pageSize parameter is ignored for external searchers.
provideTagcloud string the field name of a requested cloud. If empty, no cloud is returned empty
suppressResultList boolean if true then no result list is returned. Used for example when only the cloud is needed false
searchEngine string the identifier of the searcher to use. If empty, the default is used configurable
outputLanguage string the language to use for item label translations. If empty, the results are returned without translation. empty
suppressCorrection boolean if true then spelling correction on the input query is skipped. false
sorting ResultSorting optional result sorting definition. empty
ip string optional ip address of the request origin. If this is omitted, it is ascertained automatically when possible. empty
agent string optional user agent used in the search request for Indeed Jobs empty
uuid string optional used to uniquely and persistently identify a users browser or device. Implemented on the front end as a UUID stored in permanent local storage. Required for Broadbean search requests on CV Library. empty
suppressFacetCounts boolean Optional. If true the search responses will not contain facet count. Improves query response time. false
suppressHighlighting boolean Optional. If true search responses will not be highlighted. Note: If a snippet was requested from the searcher as part of the result fields, the snippet can still contain highlighting. false
mergeOverlappingSynonyms boolean Optional. If true the content of a query part item of type TEXT or LONG_TEXT (its term plus synonyms) that overlaps more than 75% with a previous query part of the same field and condition will be moved into the synonyms of that previous one. false
synonymLanguages list of string Optional. List of language codes preferred by the user to filter synonyms by languages. If not provided Search will select languages to use with following priority: User's saved language selection; default languages in the environment configuration; all languages defined in the environment configuration null
queryContext QueryContext Optional. Stores additional information about the query. null
synonymExpansionMode enum Optional setting for synonym expansion mode. Allowed values: QUERY, QUERY_AND_QUERYPARTS, QUERY_AND_SYNONYMMAP QUERY
useNlqs boolean Optional flag indicating that the BE needs to use the natural language query service (NLQS) should get used to interpret the query string. false


  "query": "web developer city:london+10",
  "queryParts": [
      "field": "birthdate",
      "condition": "REQUIRED",
      "weight": 1,
      "items": [
          "value": "1975-01-01..1979-12-31"
  "provideTagcloud": "compskills",
  "synonymLanguages": [
  "synonymExpansionMode": "QUERY",
  "queryContext": {
    "querySessionID": "33583ef6-1a64-4427-9bd5-f40e0a6dd852",
    "queryID": "db0e8702-f371-410c-ac4c-dadc91ef7822",
    "queryTags": [
    "matchSource": "doc://environmentName/searchEngine/documentID"
  "search_after": [