This endpoint acts as a flexible search that can be used to retrieve reviews with various metadata or with top_mentioned_topics. For example, you can use it to:
- Retrieve reviews by any metadata included in the order
- Retrieve reviews containing a specific answer to a custom question
- Retrieve reviews that include top_mentioned_topics such as size, smell, and scent
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
| Param | Type | Description |
|---|---|---|
| app_key | String | The store ID |
Query params
| Param | Type | Description |
|---|---|---|
| page | Integer | The paginated response page number to return, beginning from 1 |
| per_page | Integer | The number of results to return per page |
Body params
| Param | Type | Description |
|---|---|---|
| domain_key | String | The unique product identifier (Product ID) |
| scores | Array of integers | The review star rating score(s) to return e.g. 4 would return a 4-star reviews |
| topic_names | Array of strings | The topics mentioned in the review e.g. top_mention_topics |
| pictured | Boolean | Pass a value of true to return reviews with pictures |
| free_text_search | String | Free text search terms. Supported languages: English, French, German, Italian, Norwegian, Portuguese, Spanish, Russian, Swedish, Turkish. Learn about including synonyms |
| crfs | Array of strings | CRF object (Custom Questions/Custom Review Form) |
| question_id | Integer | The CRF question_id |
| answers | Array of strings | Answers to a custom questions |
| orders | Array of strings | Array of order hashes/strings |
| subType | String | Possible values: customer_properties, customer_custom_properties, product_properties, order_product_custom_properties, order_properties, order_custom_properties |
| question | String | The placeholder name that appear in the dropdown field |
| answers | Array of strings | The possible values that appear within the dropdown field. |
| sortings | Array of objects | See possible values in the Sortings Parameter Possible Values section below |
| sort_by | String | See possible values in the Sortings Parameter Possible Values section below |
| ascending | Boolean | Pass 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
}
}
Please note
The 'total' value in the response counts the total number of reviews for the relevant product. This includes grouped reviews and syndicated reviews
orders.subType possible values
customer_propertiescustomer_custom_propertiesproduct_propertiesorder_product_custom_propertiesorder_propertiesorder_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.