Feedback

How to Retrieve Feedback

Here some of the most popular use-cases for retrieving feedback.

To obtain all the feedback associated with my scope, a single API call is needed without specifying any filter.

POST /v3/feedbacks

This is an example of response:

More detailed info and playground in the /feedback endpoint documentation.

To obtain all the feedback associated with my scope published in a specific time frame, a single API call is needed specifying the publicationDate filter.

To deep dive into the different date filters available in the Feedback endpoint, please refer to the Date range section.

POST /v3/feedbacks

This is an example of response:

More detailed info and playground in the feedback endpoint documentation.

To obtain all the feedback associated with a specific brand, users can follow a two-step process involving querying specific API endpoints.

Query the Products Endpoint by Brand

Begin by querying the Products endpoint with the brand identifier to retrieve a list of products associated with the specified brand. This endpoint will provide you with the product IDs related to the brand.

In this case we are looking for products of the CE brand Bissell.

This is an example of response:

More detailed info and playground in the products endpoint documentation.

Query the Feedback Endpoint by Product IDs

Once you have obtained the product IDs from the Products endpoint, use these IDs to query the Feedback endpoint. By querying the Feedback endpoint with the product IDs, you can fetch all the reviews and feedback for the products associated with the specific brand.

For this example we are looking for the feedback of the first product retrieved with the previous call, with id 6762a3d1bd6fdd8288bd0824.

POST /v3/feedbacks

This is an example of response:

More detailed info and playground in the feedback endpoint documentation.

To obtain all the feedback associated with a specific product by name and brand, users can follow a two-step process involving querying specific API endpoints. In this example, we are looking for the feedback of the product 8000 Series SpeedPro Max from the brand Philips.

Query the Products Endpoint by Product name and Brand

Begin by querying the Products endpoint with the product name to retrieve a list of products associated with the specified to it. This endpoint will provide you with the product IDs.

The name and brand must be an exact match.

This is an example of response:

More detailed info and playground in the products endpoint documentation.

Query the Feedback Endpoint with Product IDs

POST /v3/feedbacks

This is an example of response:

More detailed info and playground in the feedback endpoint documentation.

To obtain all the feedback associated with a specific product page, users can follow a two-step process involving querying specific API endpoints.

Query the Pages Endpoint

Begin by querying the Pages endpoint to retrieve a list of available metadata. This endpoint will provide you with the page identifier to then query the Feedback endpoint.

In this example we want to retrieve all the reviews linked to the produc page with https://www.amazon.co.uk/dp/B01HZHYSL2

POST /v3/pages

This is an example of response:

More detailed info and playground in the /pages endpoint documentation.

Query the Feedback Endpoint with the Page ID

Once you have obtained the identifiers from the Pages endpoint, use those to query the Feedback endpoint. In this example we are looking for the feedback linked to the pageId 671378

POST /v3/feedbacks

This is an example of response:

More detailed info and playground in the feedback endpoint documentation.

To obtain all the feedback associated to the Reddit channel, users can follow a two-step process involving querying specific API endpoints.

Get the product list

Begin by querying the Products endpoint to retrieve a list of products associated with your scope. This endpoint will provide you with the product IDs.

This is an example of response:

More detailed info and playground in the products endpoint documentation.

Query the Feedback Endpoint by Product IDs

For this example we are looking for the feedback from reddit.com published in January 2025 of the first 3 products retrieved with the previous call.

POST /v3/feedbacks

This is an example of response: the post with id t3_1ibsbt3 and some of its related comments dated Jannuary 30th 2025 for one of the product fo interest.

If no language detection, nor translation nor analysis is run, the fields language, translatedText (and all other translation related fields) and annotations are expected to be empty. Since reddit.com is a social media source, there is no rating, so the value will always be 0.

More detailed info and playground in the feedback endpoint documentation.

To reconstruct a full conversation thread (post/video → comment → reply) from a social media channel, filter the Feedback endpoint by metadata.rootId, alongside the productId the thread belongs to. This returns the root post/video and every comment and reply attached to it.

POST /v3/feedbacks

This is an example of response: the root post t3_1ibsbt3, a top-level comment replying to it, and a reply to that comment.

Use parentId to build a parent→children map across all returned items; the item whose contentId equals rootId is the tree root. See Social media metadata for the full list of thread reconstruction fields.

More detailed info and playground in the /feedback endpoint documentation.

Filters

The Feedback endpoint supports a large variety of filter options to help you narrow down the results to the feedback you are interested in.

productId: product identifier
channel*: webshop or source reference
country*: country of the webshop
sku*: stock keeping unit (product identifier)
pageId: product page (URL) identifier
rating*: star value between 1 and 5
publicationDate: feedback pubblication date on the webshop
ingestionDate: feedback ingestion date in the Wonderflow data lake
metadata*: metadata associated with the feedback
feedbackWithImages*: boolean value to filter feedback with images
isIncentivizedReview*: boolean value to filter incentivized feedback
isVerifiedPurchase*: boolean value to filter verified purchase feedback
isVineVoice*: boolean value to filter Vine Voice feedback (Amazon incentivized program)

(*)The productId should always be specified when one of the following filters is applied: feedbackWithImages, isIncentivizedReview, isVerifiedPurchase, isVineVoice, channel, country, sku, rating or metadata.

Author

To ensure compliance with our data privacy policy, the author value accessible through our API from our databases is anonymized. Therefore, it will not match the original value available on the webshop.

Date range

In the Feedback schema you’ll find two fields that can be used to filter feedback by date range: publicationDate and ingestionDate.

These filters are useful to segment the data by a specific time frame and to ingest the feedback in your system incrementally.

Why are these two fields different and which one applied to which use case?

publicationDate: the date the feedback was published on the webshop
ingestionDate: the date the feedback was ingested in the Wonderflow data lake.

In a scenario where the product catalog configuration is stable in terms of product list, codes and channels, the publicationDate is the best choice to filter the feedback.

In a scenario where the product catalog configuration is not stable, so either the product list changes or product codes are added or channels are added, the publicationDate is not sufficient, since when the product catalog configuration changes new pages and new reviews are ingested in the Wonderflow data lake from scratch. In this case the ingestionDate is more suited, even if the API will return feedback where the publication date is prior to the date specified in the filter.

On the 31th Jan 2025 you query the API by publicationDate from 2025-01-01 to 2025-01-31. The API returns all the feedback published in that time frame.
On the 25th Feb 2025 the product catalog changes, adding a new SKU and new pages are scraped from scratch, storing feedback from 2023 in the Wonderflow data lake.
On the 28th Feb 2025 you query the API by publicationDate from 2025-02-01 to 2025-02-28. The API returns only the feedback published in that time frame, excluding the feedback related to the new SKU prior to that date.

If instead of using the publicationDate you filter by ingestionDate, the API will return all the feedback ingested in the Wonderflow data lake in that time frame, including the feedback related to the new SKU (starting from 2023).

The supported date format is YYYY/MM/DD

Metadata

Metadata filter options are specific for each project and dataset. Any metadata field can be used to filter the feedback records by passing metadata.<field_of_interest> as the filter name.

Some examples of metadata fields that could be available in your dataset are: age, userAge, hairColor, skinType, priceSegment, isCompetitor, …

When the channel is a social media platform, the metadata object also includes fields that let you reconstruct the full conversation thread (post/video → comment → reply).

Thread reconstruction fields

Field	Description
`contentId`	Unique identifier of the item itself: a post, a comment, a reply, or — on YouTube — a video transcription
`rootId`	ID of the top-level post/video the item belongs to. For a post/video itself, `rootId` equals `contentId`
`parentId`	ID of the item this one is a direct reply to (a comment, or the root post/video for top-level comments). Present only on comments/replies
`contentType`	Type of the item: `Post` / `Comment` (Reddit, Instagram, TikTok) or `Comment` / `Transcript` (YouTube)
`depth`	Thread nesting level, starting at 0 for top-level comments. Present only on comments/replies
`likeCount`	Number of likes the item received
`replyCount`	Number of replies/comments the item received

Use parentId to build a parent→children map across all returned items; the item whose contentId equals rootId is the tree root. Rebuilding this way (post/video → comment → reply → reply…) works the same regardless of the channel.

How to avoid the ingestion of duplicates

When you retrieve feedback from our system, you may want to avoid ingesting duplicates in your system. We suggest you to use the reviewId field to identify the feedback records. As an alternative you could create a key using the textHash, productId and the author fields.

How to Store Feedback

Here some of the most popular use-cases for storing feedback.

In this article, we are going to see how to send private data to Wonderflow Data Lake using the Wonderflow REST API.

Let’s suppose we want to add the following feedback coming from our customer care database:

{
  "author": "Author1",
  "title": "This is an example",
  "text": "Lorem ipsum",
  "language": "it",
  "rating": 5,
  "sku": "SKU1",
  "date": "2023-06-21T08:22:25.427Z",
  "additionalFields": {
    "age": 29
  }
}

In order to create this feedback entry in the Wonderflow data lake, we will have to retrieve the page we want to link the feedback to (e.g. the page containing all Call center feedback for SKU1), create a feedback and link it to the page we created.

Retrieve a page

First of all, we need to check whether the page from which this feedback comes has already been created.

✅ If the page already exists the API returns an object with all information on that page, including the pageId.

—> In this case you should skip Step 2 and go directly to Step 3.

❌ If the page does not exist the API returns an object with 0 pages.

—> In this case you need to create a page before linking the feedback records in the datalake. So proceed to Step 2.

More detailed info and playground in the get-page endpoint documentation.

Create page (if missing)

We need to create the page on the data lake

This call returns the object with the information of the created page, including the pageId.

More detailed info and playground in the create-a-page endpoint documentation.

Create feedback

Now that we have a page (retrieved or created), given pageId we obtained in the previous step, we can finally create one or more feedback records.

More detailed info and playground in the create-feedback-for-a-page endpoint documentation.

In this article, we are going to see how to send private data to Wonderflow Data Lake using the Wonderflow REST API and connect it to a previously created product card.

Important: at the present moment, you cannot create programmatically product cards via API. The cards must be configured from the Wonderboard (one by one or in bulk) prior to sending feedback. Get in touch with our Support team to deep dive on this topic.

Let’s suppose you have a CRM ticket for the SKU ESAM4200.S in your system and you want to save this record into Wonderflow Datalake and link it to the card Magnifica S from De’Longhi.

For this example, the feedback you need to link is the following:

{
  "author": "Author1",
  "title": "This is an example",
  "text": "Lorem ipsum",
  "language": "it",
  "rating": 5,
  "date": "2023-06-21T08:22:25.427Z",
  "additionalFields": {
    "age": 29
  }
}

In order to create this feedback entry in the Wonderflow data lake and link it to a product card, we will have to retrieve the page we want to link the feedback to, create a feedback and link it to the page we created and the product card.

Retrieve a page

First of all, we need to check whether the page from which this feedback comes has already been created.

✅ If the page already exists the API returns an object with all information on that page, including the pageId.

—> In this case you should skip Step 2 and go directly to Step 3.

❌ If the page does not exist the API returns an object with 0 pages.

—> In this case you need to create a page before linking the feedback records in the datalake. So proceed to Step 2.

More detailed info and playground in the get-page endpoint documentation.

Create page (if missing)

We need to create the page on the data lake

This call returns the object with the information of the created page, including the pageId.

More detailed info and playground in the create-a-page endpoint documentation.

Get product

You can query the products endpoint to retrieve the product card information either by product name or SKU, like in the following example:

This would be the API Response:

  {
    "total": 1,
    "products": [
      {
        "id": "123123123123",
        "name": "Magnifica S",
        "brandName": "DeLonghi",
        "image": "https://www.example.com/image.jpg",
        "productDivision": "Coffee",
        "productCategory": "Coffee Machines",
        "productType": "Automatic Coffee Machine",
        "skus": [
          "ESAM4200.S"
        ],
        "channels": [
          "customer-care"
        ],
        "countries": [
          "Italy"
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 100
    }
  }

We use the productId to link the feedback to the product card in the next step.

More detailed info and playground in the products endpoint documentation.

Create feedback

Now that we have a page (retrieved or created), given pageId we obtained in the previous step, we can finally create one or more feedback records.

By specifying the product identifier the system will save the CRM record in the data lake and link them automatically to the Magnifica S product card. In a matter of minutes, you can open the card in the dashboard and find the feedback analyzed.

More detailed info and playground in the create-feedback-for-a-page endpoint documentation.

API Documentation

Token

Votes

Page

Product

Analytics

Brand

Channel

User

Feedback

How to Retrieve Feedback

Filters

Author

Date range

Metadata

How to avoid the ingestion of duplicates

How to Store Feedback

API Documentation

Token

Feedback

Votes

Page

Product

Analytics

Brand

Channel

User

​How to Retrieve Feedback

​Filters

​Author

​Date range

​Metadata

​Social media metadata

​How to avoid the ingestion of duplicates

​How to Store Feedback

How to Retrieve Feedback

Filters

Author

Date range

Metadata

Social media metadata

How to avoid the ingestion of duplicates

How to Store Feedback