The Search API lets you integrate Doofinder’s search capabilities directly into your application. It handles full-text search, autocomplete, image-based search, visually similar products, and session-level event tracking.
Current version: v6 (recommended)Search API v5 is deprecated. If you are still on v5, migrate to v6 — paths changed from /5/search to /6/{hashid}/_search and the API now includes POST support, image search, and visually similar endpoints.
Base URL https://{search_zone}-search.doofinder.com
Replace {search_zone} with your zone (eu1, us1, ap1).
Authentication The Search API uses the standard Doofinder API key. The zone prefix is optional:
Authorization : Token eu1-ab46030xza33960aac71a10248489b6c26172f07
Generate keys in the Admin Panel .
Endpoints
Search GET/POST /6/{hashid}/_search — Full-text search with filters, facets, sorting, and grouping.
Suggestions GET /6/{hashid}/_suggest — Autocomplete terms as the user types.
Image Search POST /6/{hashid}/_image_search — Search by image (base64-encoded).
Visually Similar GET /6/{hashid}/_visually_similar — Find visually similar products by dfid.
Session & Event Tracking Sending session events is required for accurate stats and improved ranking via behavioral signals.
Init Session PUT /6/{hashid}/stats/init — Start a user session before the first search.
Click PUT /6/{hashid}/stats/click — Log when a user clicks a search result.
Add to Cart PUT /6/{hashid}/stats/cart/{session_id} — Log items added to cart.
Redirect PUT /6/{hashid}/stats/redirect — Log when a user follows a redirect rule.
Key Concepts hashid Every Doofinder search engine has a unique identifier called hashid (32-character hex string). All Search API paths include it:
GET /6/d8fdeab7fce96a19d3fc7b0ca7a1e98b/_search
Find your hashid in the Admin Panel under Configuration → Search Engines — hover over any engine to copy its hashid.
Indices A search engine can have multiple indices (e.g. product, page, category). By default, all indices are searched. Use the indices[] parameter to restrict to one or more:
?indices[]=product&indices[]=page
session_id and user_id Track user sessions and identities to enable personalization and accurate analytics:
Field Max length Description session_id32 chars Unique per browsing session. Generate a new one per visit. user_id36 chars Persistent user identifier (e.g. UUID). Enables cross-session personalization.
Filters and Facets Filter parameters Narrow results by field values. Term filters accept arrays; range filters use gte, lte, gt, lt:
filter[color][]=blue&filter[color][]=red&filter[price][gte]=10&filter[price][lte]=100
URL-encode brackets: [ → %5B, ] → %5D.
For complex filters, use the POST variant and send a JSON body:
{ "query" : "shoes" , "filter" : { "color" : [ "blue" , "red" ], "price" : { "gte" : 10 , "lte" : 100 } } }
Facet aggregations Request aggregations to power filter UI:
facets[0][field]=brand&facets[0][size]=10&facets[1][field]=price&facets[1][type]=range
The response includes term counts and range min/max for each requested facet.
Doofinder supports multiple prices per product (e.g. for different currencies or customer groups). Index your items with price fields named using the convention price_{name} (e.g. price_eur, price_usd, price_member).
To filter by a specific price field:
filter[price_eur][gte]=10&filter[price_eur][lte]=100
To sort by a specific price:
The price_name parameter in the Recommendations API body accepts the currency code (e.g. "EUR") to format prices in the response.
Grouping and Variants When your catalogue has product variants (e.g. different sizes/colors of the same product), use grouping to collapse them into a single result:
Parameter Default Description groupingfrom Admin config Collapse variants sharing the same df_grouping_id with_variants[]— When grouping is on, include these fields from each variant
{ "query" : "t-shirt" , "grouping" : true , "with_variants" : [ "size" , "color" , "price" ] }
Query Types Doofinder automatically picks the best query strategy, but you can override it with query_name:
Value Behavior match_andAll terms must appear in results match_orAny term can appear (higher score if all match) fuzzyApplies fuzzy matching for typo tolerance
The response always includes query_name so you can see which strategy was used. 
