---
updatedAt: 2026-10-29T11:54:48.000Z
agentTools:
  projectIndex: https://docs.yotpo.com/llms.txt
---

# Best Sentences

This endpoint automatically retrieves the very best sentences from your Yotpo reviews, so you can leverage the social proof of top customer testimonials at key conversion points throughout the buyer journey! You define the star-rating score, sentence length, and more!

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "App partners API",
    "description": "Endpoints for apps that Yotpo merchants install. The app-level webhook is defined separately, in webhooks.json.",
    "version": "2"
  },
  "servers": [
    {
      "url": "https://developers.yotpo.com"
    }
  ],
  "security": [
    {
      "X-Yotpo-Token": []
    }
  ],
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "paths": {
    "/v2/{account_id}/best_sentences": {
      "post": {
        "summary": "Best Sentences",
        "description": "This endpoint automatically retrieves the very best sentences from your Yotpo reviews, so you can leverage the social proof of top customer testimonials at key conversion points throughout the buyer journey! You define the star-rating score, sentence length, and more!",
        "operationId": "best-sentences",
        "parameters": [
          {
            "name": "account_id",
            "in": "path",
            "description": "Your Yotpo App Key",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "minimum_sentence_length": {
                    "type": "integer",
                    "description": "Define the minimum length of best sentences by character count. Must be less than the `maximum_sentence_length`. Default: 20 chars",
                    "format": "int32"
                  },
                  "maximum_sentence_length": {
                    "type": "integer",
                    "description": "Define the maximum length of best sentences by character count. Must be greater than the `minimum_sentence_length`. Default: 100 chars",
                    "format": "int32"
                  },
                  "maximum_number_of_sentences": {
                    "type": "integer",
                    "description": "Define the maximum number of sentences to return for this request. Default: 3 sentences",
                    "format": "int32"
                  },
                  "start_date": {
                    "type": "string",
                    "description": "Start date and time of your request.  YYYY-MM-DDT00:00:00.000Z",
                    "format": "date"
                  },
                  "end_date": {
                    "type": "string",
                    "description": "End date and time of your request.  YYYY-MM-DDT00:00:00.000Z",
                    "format": "date"
                  },
                  "external_product_ids": {
                    "type": "array",
                    "description": "Product ID. Supports multiple products.  This parameter is also sometimes referred to as `SKU` or `domain_key`",
                    "items": {
                      "type": "string"
                    }
                  },
                  "product_groups": {
                    "type": "string",
                    "description": "The name of a product group."
                  },
                  "product_collections": {
                    "type": "string",
                    "description": "The name of a product collection"
                  },
                  "minimum_score": {
                    "type": "integer",
                    "description": "Filter by minimum star-rating.  Must be an integer between 1 and 5(stars) Default: 4",
                    "format": "int32"
                  },
                  "exclude_unpublished": {
                    "type": "boolean",
                    "description": "Passing this param as `true` will only return best sentences from published reviews."
                  }
                }
              },
              "examples": {
                "Body": {
                  "value": {
                    "minimum_sentence_length": 20,
                    "maximum_sentence_length": 100,
                    "maximum_number_of_sentences": 3,
                    "start_date": "2017-01-13T00:00:00.000Z",
                    "end_date": "2018-05-13T00:00:00.000Z",
                    "external_product_ids": [],
                    "product_groups": [],
                    "product_collections": [],
                    "minimum_score": 4,
                    "exclude_unpublished": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"review_sentences\": [\n        {\n            \"review_id\": 47084341,\n            \"sentence\": \"this web site is a great place to get very cute bracelets, necklaces, or rings!\",\n            \"external_product_id\": \"5420399557\",\n            \"topics\": [\n                \"necklace\",\n                \"brackets\",\n                \"place\",\n                \"website\"\n            ]\n        },\n        {\n            \"review_id\": 43408798,\n            \"sentence\": \"quality and value are great as well.\",\n            \"external_product_id\": \"5420399557\",\n            \"topics\": [\n                \"quality\",\n                \"value\"\n            ]\n        },\n        {\n            \"review_id\": 42210491,\n            \"sentence\": \"i love your bracelets and the amazing color, designs and awareness.\",\n            \"external_product_id\": \"5420399557\",\n            \"topics\": [\n                \"awareness\",\n                \"company\",\n                \"design\",\n                \"colors\"\n            ]\n        }\n    ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "review_sentences": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "review_id": {
                            "type": "integer",
                            "example": 47084341,
                            "default": 0
                          },
                          "sentence": {
                            "type": "string",
                            "example": "this web site is a great place to get very cute bracelets, necklaces, or rings!"
                          },
                          "external_product_id": {
                            "type": "string",
                            "example": "5420399557"
                          },
                          "topics": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "example": "necklace"
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid access token. Send a valid token in the `X-Yotpo-Token` header.",
            "content": {
              "application/json": {
                "examples": {
                  "Missing token": {
                    "summary": "No token sent (or sent as Authorization: Bearer)",
                    "value": {
                      "error": "invalid_request",
                      "error_description": "The access token is missing"
                    }
                  },
                  "Invalid token": {
                    "summary": "Token unknown, revoked or for another app",
                    "value": {
                      "error": "invalid_token",
                      "error_description": "The access token is invalid or has expired"
                    }
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "OAuth error code: `invalid_request` when no token was sent, `invalid_token` when the token is unknown, revoked or expired.",
                      "enum": [
                        "invalid_request",
                        "invalid_token"
                      ]
                    },
                    "error_description": {
                      "type": "string",
                      "description": "Human-readable reason for the error."
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "components": {
    "securitySchemes": {
      "X-Yotpo-Token": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Yotpo-Token",
        "description": "Send your app's access token for the merchant's store in the `X-Yotpo-Token` header of every request. To get a token, see [Generate Access Token](ref:generate-a-token). The API also reads the token from an `access_token` query parameter, but that isn't recommended: URLs end up in server and proxy logs. `Authorization: Bearer` is not supported."
      }
    }
  }
}
```

# Sibling pages

* [Introduction to Reviews](https://docs.yotpo.com/reference/introduction-to-reviews.md)
* [All Reviews](https://docs.yotpo.com/reference/all-reviews.md)
* [Product Reviews](https://docs.yotpo.com/reference/product-review.md)
* [Product Star Rating](https://docs.yotpo.com/reference/bottomline.md)
* [Review by Review ID](https://docs.yotpo.com/reference/reviews-id.md)
* [Top Reviews](https://docs.yotpo.com/reference/top-reviews.md)
* [Best Reviews](https://docs.yotpo.com/reference/best-reviews.md)
* [Publish/Unpublish Reviews](https://docs.yotpo.com/reference/publishunpublish-reviews.md)