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

Param

Type

Description

app_key

String

Your Yotpo account API key

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. Including synonyms: https://sites.google.com/site/kevinbouge/synonyms-lists

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
    }
}

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 }

👍

Rate limit & data freshness SLA applies!

  • Requests for this endpoint are limited to 30,000 requests/minute, per IP address.
  • Data retrieved by this endpoint will be no older than 3 hours.