Initialize guide ▶️

POST /navigation/guide/init

Initialize a new guided search.

A guided search will take several steps to go through, thus it is identified by a search_id which must be provided at each step.

The search_id holds all user choices made at each step of the guide.

For advanced usages, it is possible to provide some filters at search init, that will be used immediately on the rest of the search. The syntax of the filters requires some knowledged about the keys of the used properties and values and is not meant to be guessed without prior knowledge.


  • optional_filters array[string]

    Optional filters that will reduce the product population to search into

  • If enabled, will only show custom pictograms, not Deck default ones


  • 200 object

    Successfully initialized guided search

    • status string
    • result object
      • context object
        • locale string

          Available languages depend on your corporation settings

          Value is en fr it es de hu ja be pt es fi ro tr pt-BR es-AR.

        • The search_id include all user choices, built or edited at each stage of the search guide

        • True if only custom pictograms are returned, but not Deck default pictograms

        • step integer

          The current step of the search, to be used to identify the question we're answering to

        • Total product count at current step

        • The API endpoint to follow search guide while there are still some steps to follow

        • The API endpoint to refine your search once you followed all the steps

        • The API endpoint to get search guide results

POST /navigation/guide/init
curl \
 -X POST \
 -H "PPEApiKey: $API_KEY" \
 -H "Content-Type: application/json" \
 -d '{"optional_filters":["my-prop1~my-value","other-prop2~other-value"],"custom_pictos_only":true}'
Request example
  "optional_filters": [
  "custom_pictos_only": true
Response example (200)
  "status": "OK",
  "result": {
    "context": {
      "locale": "en",
      "search_id": "2e254ef2-3e63-4cb2-9680-3876b68e7191",
      "custom_pictos_only": true,
      "step": 1,
      "product_count": 4513,
      "api_follow_guide": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/en/follow/current",
      "api_guide_results": "/api/v1/navigation/guide/2e254ef2-3e63-4cb2-9680-3876b68e7191/en/results"