Search reviews

Once top_mentioned_topics a retrieved for a given product(s), this endpoint can be used to fetch reviews affiliated with those topics.

For example, if top_mentioned_topics are size, smell, and scent - this endpoint would be used to fetch all the reviews in which size, smell, and scent are mentioned.

POST | https://api-cdn.yotpo.com/v1/reviews/app_key/filter.json

{
    "domain_key": "95035719697",
    "scores": [],
    "topic_names": ["style", "straps"],
    "pictured": false,
    "orders": [{
        "subType": "customer_properties",
        "question": "state",
        "answers": [
            "Boston"
        ]
    }],
    "sortings": [{
        "sort_by": "votes_up",
        "ascending": false
    }],
    "per_page": 10
}
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "pagination": {
            "page": 1,
            "per_page": 1,
            "total": 2
        },
        "grouping_data": {},
        "products": [
            {
                "id": 70657043,
                "domain_key": "95035719697",
                "name": "24/7TM Cotton T-Shirt Bra",
                "social_links": {
                    "facebook": "https://yotpo.com/go/akRE3Z9B",
                    "twitter": "https://yotpo.com/go/ebubSXTt",
                    "linkedin": "https://yotpo.com/go/y3YrkfjM",
                    "google_oauth2": "https://yotpo.com/go/pWHrvVTP"
                },
                "embedded_widget_link": "https://yotpo.com/go/58oL2P53",
                "testimonials_product_link": "https://yotpo.com/go/7vv4tQHk",
                "product_link": "https://yotpo.com/go/4ZD1E1Ua",
                "image_url": null
            }
        ],
        "reviews": [
            {
                "id": 70491279,
                "score": 5,
                "votes_up": 3,
                "votes_down": 0,
                "content": "This bra is exactly what I've been waiting for: breathable comfort and a cute, casual style. I love the keyhole cutout and it fits great, too!",
                "title": "My New Favorite",
                "created_at": "2018-10-10T23:34:46.000Z",
                "verified_buyer": false,
                "source_review_id": null,
                "sentiment": 0.991569,
                "topics": {
                    "comfort": {
                        "name": "comfort",
                        "sentence": "This bra is exactly what I've been waiting for: breathable comfort and a cute, casual style."
                    },
                    "cutout": {
                        "name": "cutout",
                        "sentence": "I love the keyhole cutout and it fits great, too!"
                    },
                    "fit": {
                        "name": "fit",
                        "sentence": "I love the keyhole cutout and it fits great, too!"
                    },
                    "style": {
                        "name": "style",
                        "sentence": "This bra is exactly what I've been waiting for: breathable comfort and a cute, casual style."
                    }
                },
                "fields_highlights": {},
                "custom_fields": null,
                "product_id": 70657043,
                "user": {
                    "user_id": 20604665,
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "user_type": "User",
                    "is_social_connected": 0,
                    "display_name": "Nicole Y."
                }
            }
        ],
        "found_filtered_reviews": true
    }
}
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "pagination": {
            "page": 1,
            "per_page": 5,
            "total": 222
        },
        "grouping_data": {},
        "products": [
            {
                "id": 68701220,
                "domain_key": "538465337388",
                "name": "Brazilian Bum Bum Cream",
                "social_links": {
                    "facebook": "https://yotpo.com/go/6z8hDc4s",
                    "twitter": "https://yotpo.com/go/yztUcDk3",
                    "linkedin": "https://yotpo.com/go/w1i777YD",
                    "google_oauth2": "https://yotpo.com/go/kZn7yarP"
                },
                "embedded_widget_link": "https://yotpo.com/go/iu0Civar",
                "testimonials_product_link": "https://yotpo.com/go/tWXclTgr",
                "product_link": "https://yotpo.com/go/3rrBmmOz",
                "image_url": null
            }
        ],
        "product_tags": [],
        "reviews": [
            {
                "id": 70598161,
                "score": 5,
                "votes_up": 0,
                "votes_down": 0,
                "content": "Amazing lotion",
                "title": "LOVE this scent",
                "created_at": "2018-10-12T04:28:10.000Z",
                "verified_buyer": true,
                "source_review_id": null,
                "sentiment": 0.984246,
                "topics": {
                    "lotion": {
                        "name": "lotion",
                        "sentence": "Amazing lotion"
                    }
                },
                "fields_highlights": {
                    "review_content": [
                        "lotion"
                    ]
                },
                "custom_fields": {
                    "--14860": {
                        "title": "What I Love",
                        "form_id": 11849,
                        "field_type": "MultipleChoice",
                        "value": "Hydrates Skin, Smells Great, Absorbs Quickly, Not Greasy"
                    },
                    "--14856": {
                        "title": "Skin Hydration",
                        "form_id": 11849,
                        "field_type": "Rating",
                        "value": 5
                    },
                    "--14857": {
                        "title": "Absorption Speed",
                        "form_id": 11849,
                        "field_type": "Rating",
                        "value": 4
                    },
                    "--14855": {
                        "title": "Scent",
                        "form_id": 11849,
                        "field_type": "Rating",
                        "value": 5
                    },
                    "--14858": {
                        "title": "Age",
                        "form_id": 11849,
                        "field_type": "SingleChoice",
                        "value": "55 - 64"
                    },
                    "--14859": {
                        "title": "Skin Type",
                        "form_id": 11849,
                        "field_type": "MultipleChoice",
                        "value": "Dry"
                    }
                },
                "product_id": 68701220,
                "user": {
                    "user_id": 113769,
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "user_type": "User",
                    "is_social_connected": 0,
                    "display_name": "Carol B."
                }
            }
        ],
        "found_filtered_reviews": true
    }
}

Path params

ParamTypeDescription
app_keyStringThe store ID

Query params

ParamTypeDescription
pageIntegerThe paginated response page number to return, beginning from 1
per_pageIntegerThe number of results to return per page

Body params

ParamTypeDescription
domain_keyStringThe unique product identifier (Product ID)
scoresArray of integersThe review star rating score(s) to return e.g. 4 would return a 4-star reviews
topic_namesArray of stringsThe topics mentioned in the review e.g. top_mention_topics
picturedBooleanPass a value of true to return reviews with pictures
free_text_searchStringFree text search terms. Supported languages: English, French, German, Italian, Norwegian, Portuguese, Spanish, Russian, Swedish, Turkish. Learn about including synonyms
crfs Array of stringsCRF object (Custom Questions/Custom Review Form)
question_idIntegerThe CRF question_id
answersArray of stringsAnswers to a custom questions
orders Array of stringsArray of order hashes/strings
subTypeStringPossible values: customer_properties, customer_custom_properties, product_properties, order_product_custom_properties, order_properties, order_custom_properties
questionStringThe placeholder name that appear in the dropdown field
answersArray of stringsThe possible values that appear within the dropdown field.
sortingsArray of objectsSee possible values in the Sortings Parameter Possible Values section below
sort_byStringSee possible values in the Sortings Parameter Possible Values section below
ascendingBooleanPass a value of true to sort in ascending order or false to sort in descending order

Results

{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "pagination": {
            "page": 1,
            "per_page": 1,
            "total": 2
        },
        "grouping_data": {},
        "products": [
            {
                "id": 70657043,
                "domain_key": "95035719697",
                "name": "24/7TM Cotton T-Shirt Bra",
                "social_links": {
                    "facebook": "https://yotpo.com/go/akRE3Z9B",
                    "twitter": "https://yotpo.com/go/ebubSXTt",
                    "linkedin": "https://yotpo.com/go/y3YrkfjM",
                    "google_oauth2": "https://yotpo.com/go/pWHrvVTP"
                },
                "embedded_widget_link": "https://yotpo.com/go/58oL2P53",
                "testimonials_product_link": "https://yotpo.com/go/7vv4tQHk",
                "product_link": "https://yotpo.com/go/4ZD1E1Ua",
                "image_url": null
            }
        ],
        "reviews": [
            {
                "id": 70491279,
                "score": 5,
                "votes_up": 3,
                "votes_down": 0,
                "content": "This bra is exactly what I've been waiting for: breathable comfort and a cute, casual style. I love the keyhole cutout and it fits great, too!",
                "title": "My New Favorite",
                "created_at": "2018-10-10T23:34:46.000Z",
                "verified_buyer": false,
                "source_review_id": null,
                "sentiment": 0.991569,
                "topics": {
                    "comfort": {
                        "name": "comfort",
                        "sentence": "This bra is exactly what I've been waiting for: breathable comfort and a cute, casual style."
                    },
                    "cutout": {
                        "name": "cutout",
                        "sentence": "I love the keyhole cutout and it fits great, too!"
                    },
                    "fit": {
                        "name": "fit",
                        "sentence": "I love the keyhole cutout and it fits great, too!"
                    },
                    "style": {
                        "name": "style",
                        "sentence": "This bra is exactly what I've been waiting for: breathable comfort and a cute, casual style."
                    }
                },
                "fields_highlights": {},
                "custom_fields": null,
                "product_id": 70657043,
                "user": {
                    "user_id": 20604665,
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "user_type": "User",
                    "is_social_connected": 0,
                    "display_name": "Nicole Y."
                }
            }
        ],
        "found_filtered_reviews": true
    }
}
{
    "status": {
        "code": 200,
        "message": "OK"
    },
    "response": {
        "pagination": {
            "page": 1,
            "per_page": 5,
            "total": 222
        },
        "grouping_data": {},
        "products": [
            {
                "id": 68701220,
                "domain_key": "538465337388",
                "name": "Brazilian Bum Bum Cream",
                "social_links": {
                    "facebook": "https://yotpo.com/go/6z8hDc4s",
                    "twitter": "https://yotpo.com/go/yztUcDk3",
                    "linkedin": "https://yotpo.com/go/w1i777YD",
                    "google_oauth2": "https://yotpo.com/go/kZn7yarP"
                },
                "embedded_widget_link": "https://yotpo.com/go/iu0Civar",
                "testimonials_product_link": "https://yotpo.com/go/tWXclTgr",
                "product_link": "https://yotpo.com/go/3rrBmmOz",
                "image_url": null
            }
        ],
        "product_tags": [],
        "reviews": [
            {
                "id": 70598161,
                "score": 5,
                "votes_up": 0,
                "votes_down": 0,
                "content": "Amazing lotion",
                "title": "LOVE this scent",
                "created_at": "2018-10-12T04:28:10.000Z",
                "verified_buyer": true,
                "source_review_id": null,
                "sentiment": 0.984246,
                "topics": {
                    "lotion": {
                        "name": "lotion",
                        "sentence": "Amazing lotion"
                    }
                },
                "fields_highlights": {
                    "review_content": [
                        "lotion"
                    ]
                },
                "custom_fields": {
                    "--14860": {
                        "title": "What I Love",
                        "form_id": 11849,
                        "field_type": "MultipleChoice",
                        "value": "Hydrates Skin, Smells Great, Absorbs Quickly, Not Greasy"
                    },
                    "--14856": {
                        "title": "Skin Hydration",
                        "form_id": 11849,
                        "field_type": "Rating",
                        "value": 5
                    },
                    "--14857": {
                        "title": "Absorption Speed",
                        "form_id": 11849,
                        "field_type": "Rating",
                        "value": 4
                    },
                    "--14855": {
                        "title": "Scent",
                        "form_id": 11849,
                        "field_type": "Rating",
                        "value": 5
                    },
                    "--14858": {
                        "title": "Age",
                        "form_id": 11849,
                        "field_type": "SingleChoice",
                        "value": "55 - 64"
                    },
                    "--14859": {
                        "title": "Skin Type",
                        "form_id": 11849,
                        "field_type": "MultipleChoice",
                        "value": "Dry"
                    }
                },
                "product_id": 68701220,
                "user": {
                    "user_id": 113769,
                    "social_image": "https://ddcfq0gxiontw.cloudfront.net/images/anonymous_user.png",
                    "user_type": "User",
                    "is_social_connected": 0,
                    "display_name": "Carol B."
                }
            }
        ],
        "found_filtered_reviews": true
    }
}

orders.subType possible values

  • customer_properties
  • customer_custom_properties
  • product_properties
  • order_product_custom_properties
  • order_properties
  • order_custom_properties

Sortings parameter possible values

'elastic_search_score' => { 'sort_by': '_score', 'ascending': false },
    'badge' => { 'sort_by': 'reviewer_type', 'ascending': false },
    'score' => { 'sort_by': 'score', 'ascending': false },
    'low_score' => { 'sort_by': 'score', 'ascending': true },
    'date' => { 'sort_by': 'date', 'ascending': false },
    'votes' => { 'sort_by': 'votes_up', 'ascending': false },
    'low_votes' => { 'sort_by': 'votes_down', 'ascending': false },
    'images' => { 'sort_by': 'image_count', 'ascending': false },
    'grouping' => { 'sort_by': 'grouping_originated', 'ascending': true }

👍

How to use this endpoint

  • Requests for this endpoint are limited to 30,000 requests/minute, per IP address.
  • Data is retrieved with a delay of 3 hours.