Topics

POST/insights/v1/topics

Use it in a workflow

Add a step and choose the Yotpo connector.
Pick the Topics action (under Reviews & Ratings).
Fill in the fields below, then reference the result from later steps as {{topics.response.data}}.

Request

Headers

content typestring

application /JSON

authorizationstring

Bearer <### Your uToken goes here ###> e.g. Bearer YTJZm0J7XaIcpzVN8HsWzhOcAzwdbzFJ1HDQJXSk

Request body

Enter the body as JSON in the step's Body field.

app_keystringrequired

The store ID

start_datestring (date)

Start date and time of your request. YYYY-MM-DDT00:00:00.000Z

end_datestring (date)

End date and time of your request. YYYY-MM-DDT00:00:00.000Z

minimum_mentionsinteger (int32)

The minimum number of times this topic was mentioned Should always be set to no less than 10 mentions Topics associated with a low number of opinions may result in a statistically insignificant sentiment score. Default: 0

external_product_idsarray<string>

The unique product IDs (supports multiple products). This parameter is also sometimes referred to as SKU or `domain_key`

countriesarray<string>

Abbreviation of reviewer origin country (e.g US). Supports multiple countries. [See List](https://github.com/pariz/gountries/tree/master/data/json/countries)

statesarray<string>

Abbreviation of reviewer origin state (e.g. CA, NY,). Supports multiple states. [See List](https://github.com/YotpoLtd/country-states/blob/master/us.go)

product_grouparray<string>

The name of the product group as defined in your Yotpo product catalog

product_collectionsarray<string>

The name of the product collection as defined in your Yotpo product catalog

minimum_scoreinteger (int32)

Filter by minimum star-rating. Must be an integer between 1 and 5(stars)

topicsarray<string>

The name of the topic. Supports multiple topics.

pageinteger (int32)

Page number

per_pageinteger (int32)

Results per page. Default: 0

sorting_fieldstring

Accepted values: `yotpo_default_sorting`,`sentiment_score`,`positive_mentions`,`negative_mentions`,`topic` (alphabetically) Note: `yotpo_default_sorting` leverages a sorting logic which includes sentiment score, and the number of opinions to surface the most significant and polarized topics. This sorting parameter is equal to "most relevant" in the Insights dashboard.

sorting_directionstring

ASC or DESC (Case sensitive)

json

{
  "app_key": "string",
  "start_date": "2025-01-01",
  "end_date": "2025-01-01",
  "minimum_mentions": 0,
  "external_product_ids": [
    "string"
  ],
  "countries": [
    "string"
  ],
  "states": [
    "string"
  ],
  "product_group": [
    "string"
  ],
  "product_collections": [
    "string"
  ],
  "minimum_score": 0,
  "topics": [
    "string"
  ],
  "page": 0
}

Response

Returns 200 with an object. Read it in later steps with {{topics.response.data.<field>}}.

topicsarray<object>

topicstring

sentiment_scorenumber

Default 0

industry_averageobject2 fields

sentiment_changeobject2 fields

positive_mentionsinteger

Default 0

negative_mentionsinteger

Default 0

neutral_mentionsinteger

Default 0

products_countinteger

Default 0

opinions_countinteger

Default 0

included_keywordsarray<any>

pagingobject

pageinteger

Default 0

page_countinteger

Default 0

per_pageinteger

Default 0

totalinteger

Default 0

json

{
  "topics": [
    {
      "topic": "flavor",
      "sentiment_score": 44.334976,
      "industry_average": {
        "value": 51.5839958190918,
        "error": ""
      },
      "sentiment_change": {
        "value": -14.511178476695719,
        "error": ""
      },
      "positive_mentions": 131,
      "negative_mentions": 41,
      "neutral_mentions": 31,
      "products_count": 3,
      "opinions_count": 203,
      "included_keywords": [
        null
      ]
    }
  ],
  "paging": {
    "page": 0,
    "page_count": 1,
    "per_page": 10,
    "total": 1
  }
}

Need more? See the Yotpo guide for connection setup and behaviour shared by every action.

Was this page helpful?