> For the complete documentation index, see [llms.txt](https://docs.fact-finder.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fact-finder.com/integration/factfinder-search-integration/fact-finder-search-parameters.md). # FactFinder search parameters When you send a search request to the FactFinder Search server through the REST API, you can use several parameters to control which results are returned and how they are returned. Some parameters are required. Others are optional or only relevant in specific cases. Whenever you send data to FactFinder, make sure the encoding is set correctly. UTF-8 is the default and required encoding for handling special characters correctly. > The available search parameters are also documented in the Search application’s **Swagger UI** under the `search` method. ## Basic Parameters These are the fundamental parameters that are commonly used in nearly every search request: * `query` *(string, required)* – The search term or phrase to look up in the FactFinder database. This parameter, together with `channel`, is mandatory for every search request. It represents what the user is searching for. * `channel` *(string, required, path)* – The identifier of the channel to search in. If the search environment contains multiple channels, such as one per language or product category, this parameter specifies which channel to use. If no channel is specified, the system uses the first channel configured on the server. * `page` *(integer)* – The page number of results to retrieve. Search results are paginated when there are more items than the default page size. This parameter lets you request a specific result page. Page numbering starts at 1, so `page=1` is the first page. * `hitsPerPage` *(integer)* – The number of results to return per page. The FactFinder Management Interface defines a default number of hits per page. Using `hitsPerPage` overrides that default for a given query. For example, `hitsPerPage=20` requests 20 results. If you do not specify a value, the configured default is used. * `sort` *(array of string)* – Sorting criteria for the results, other than the default relevance sort. You can specify one or more sort criteria. Each criterion is usually written as `FieldName:order`, where `order` is `asc` or `desc`. If multiple criteria are provided, they are applied in sequence. For example, `sort=Manufacturer:asc` sorts results by the "Manufacturer" field in ascending order. * `filter` *(array of string)* – Filters the results by specific field values. A filter restricts the result set to records that contain certain values in a field, often for category or attribute filtering. The format is usually `filter=FieldName:Value`. A filter can have multiple values. The values can be separated with the following characters, which are configurable in `config.xml`: * ‘and’ = `___` * ‘or’ = `~~~` A filter value can be excluded with the prefix `!`. For example, `filter=color:Red~~~!Green` can be interpreted as *color is Red OR color is NOT Green*. In this example, `~~~` acts as an OR separator between "Red" and "!Green". The `!` prefix before "Green" excludes that value. Numeric filters use the standard mathematical interval notation, but only intervals that are closed on the left side and open on the right side are allowed as input. Thus, only intervals of the form `[a,b)`, `[a,)`, or `[a,]` are allowed. Square brackets `[` `]` denote inclusive boundaries and parentheses `(` `)` denote exclusive boundaries. For values of type date, the same notation as for numeric filters can be used. For example, to include all items with a start date within the 1990s, a filter could be: `filter=startdate1: [1990-01-01T00:00:00+00:00,2000-01-01T00:00:00+00:00)`. The format of the date can be either ISO-8601 with timezone (yyyy-MM-dd'T'HH:flag\_mm:ssZZ), a Unix timestamp in milliseconds, or the format that is defined for the specific field. * `substringFilter` *(array of string)* – Filters for a substring of the field value. A filter can have multiple values. The values can be separated with the following characters, which are configurable in `config.xml`: ‘and’ = `___` ‘or’ = `~~~` A filter value can be excluded with the prefix `!`. * `searchField` *(string)* – While FactFinder normally searches all searchable fields, this parameter restricts the search to a single field. * `articleNumberSearch` *(string)* – Specifies whether the query should be interpreted as an article number. The default value is `DETECT`. * `sid` *(string)* – Represents the session ID associated with the search request. * `userInput` *(string)* – Transmits the characters entered by the shop user before the search query was triggered. * `queryFromSuggest` *(boolean)* – Indicates that the query was initiated from the suggestion list. In that case, send the parameter with the value `true`. ## Parameters used to control the search process * `useSearch` *(boolean)* - If set to `true`, the search will be executed for the provided query. The default value for this parameter is `true`. * `useAsn` *(boolean)* - If set to `true`, filters should be generated for the search results. The default value for this parameter is `true`. * `useFoundWords` *(boolean)* - Controls whether the words that were used to locate the data records are returned for the found results. Determining these words requires CPU time, and for this reason, this function is disabled by default (`false`). Set the parameter to `true` to enable the generation of search words or `false` if search words are not required. The default value is `false`. * `useCampaigns` *(boolean)* - Controls whether the Campaign Manager evaluates if the search query matches a configured campaign. If set to `true`, campaigns are evaluated and returned as appropriate. If set to `false`, campaigns are ignored. * `idsOnly` *(boolean)* - By default, the search result includes all field information for the found products. If you only need product IDs, set this parameter to `true`. That prevents field content from being returned and saves bandwidth. The default value is `false`. * `useCache` *(boolean)* - If set to `true`, the search result will be returned from the cache memory if a possible matching result already exists in the cache. The default value for this parameter is `true`. * `cacheIrrelevant` *(array of string)* - Used to flag specific parameters as irrelevant for caching purposes. * `usePersonalization` *(boolean)* - Allows for the activation or deactivation of query personalization. If set to `true`, the search result will be personalized, provided the personalization module is activated and all other relevant requirements are met. If set to `false`, the search result will not be personalized. The default value for this parameter is `true`. * `useSemanticEnhancer` *(boolean)* - Allows for the activation or deactivation of the semantic enhancement of queries. If set to `true`, the search result will be semantically enhanced, provided the enhancer module is activated and all other relevant requirements are met. If set to `false`, semantic enhancement is not applied. The default value for this parameter is `true`. * `useAso` *(boolean)* - Allows for the activation or deactivation of automatic search optimization. If set to `true`, the search result will be optimized automatically. If set to `false`, the search result will not be optimized. The default value for this parameter is `true`. * `maxCountVariants` *(integer)* - If product variants are used in the data (for example, a product that has multiple variants like different sizes or colors), this parameter defines the maximum number of variant items to return for each main product record in the results. This can be used to limit how many variants are returned to avoid an overly large response. * `advisorStatus` *(string)* - Used with Advisor, a guided selling or campaign feature. This parameter can carry the current campaign ID and the user’s answer path in a guided selling flow. The format is typically `campaignId-answerPath`. It tells FactFinder the current state of the dialog when the query is processed. * `useDeduplication` *(boolean)* - If set to `true`, the configured deduplication of variants will be applied to the search results. The default value for this parameter is `true`. * `deduplicationField` *(string)* - Specifies the field upon which variants should be deduplicated. ## Additional parameters * `format` - The response format of the search results. Because the XML and JSON interfaces are invoked through a URL, this parameter specifies which format should be returned. If no value is provided, the result is returned in HTML format by default. Supported values are `xml`, `json`, and `jsonp`. * `version` - FactFinder provides versioned APIs to support smoother migrations. This makes it possible to update to a newer FactFinder version without changing the integration code immediately. You can then update the integration later to use new features. In FactFinder 7.2, the values `6.11`, `7.0`, `7.1`, and `7.2` are supported. A default version is usually configured in the application settings, so you normally do not need to pass this parameter explicitly. * `omitContextName` - If you pass `true`, returned search parameter URLs begin with the action name instead of the FactFinder application name. This can be useful in load-balanced setups where different FactFinder applications use different names. It can also reduce the amount of transmitted data in standard deployments. * `log` - An optional parameter that attaches a custom description string to the search request for logging. It must be passed in addition to the search query. This is useful when you want to evaluate only certain search requests. The provided description remains visible during log analysis. The value should contain only letters and numbers. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.fact-finder.com/integration/factfinder-search-integration/fact-finder-search-parameters.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.