Skip to main content
Skip table of contents

API Quick Reference

This article provides a quick reference for the most frequently used API endpoints. Read the TurnTo API reference documentation for a complete listing of endpoints and parameters available in the REST API.

Cache any calls related to information retrieval.

Obtaining the primary access token

To obtain a primary API access token, submit a POST request to the /oauth2/token endpoint with the following request body:

client_id=<SITE KEY>&client_secret=<AUTH KEY>&grant_type=client_credentials

Replace <SITE KEY> and <AUTH KEY> with the values provided in Emplifi Ratings & Reviews.

Once generated, a primary API access token does not expire.

Do not share or expose the primary API access token.

Additional API reference documentation: OAuth.

Do not request a new primary access token each time you call the API. Emplifi Ratings & Reviews does not automatically invalidate the primary access token. Consider using a persistent cache to limit the number of calls for the token. If your security process requires the token be renewed periodically, you can invalidate the access token and request a new one.

Invalidating the primary access token

Access tokens do not expire. Only invalidate your primary API access token if it has been compromised or you have a security policy that requires periodically renewing it.

To invalidate the primary access token, submit a POST request to the /oauth2/invalidate_token endpoint with the following request body:

client_id=<SITE KEY>&client_secret=<AUTH KEY>&access_token=<PRIMARY ACCESS TOKEN>

Replace <SITE KEY> and <AUTH KEY> with the values in Emplifi Ratings & Reviews.

Once the primary access token is invalidated, API requests using the invalid token will result in authorization errors.

Additional API reference documentation: OAuth.

Pulling subdimensions for a SKU

If your site has only one global subdimension, you can call this endpoint one time in order to collect the subdimension ID and store it somewhere. If your site has dynamic subdimensions (based on category, for example), you may want to call this API endpoint before creating the review form in order to know what subdimension labels to display on the form.

GET https://api.turnto.com/v1.3/products?sku=<SKU>

Part of the response includes a JSON string. Here's an example:

JSON 
{
  "dimensions": [
    {
      "id": 1,
      "sortOrder": 2,
      "label": "Fit",
      "type": 2,
      "required": false,
      "average": 1.21,
      "values": [
        {
          "id": 2,
          "sortOrder": 0,
          "label": "Runs Small"
        },
        {
          "id": 3,
          "sortOrder": 1,
          "label": "True to Size"
        },
        {
          "id": 4,
          "sortOrder": 2,
          "label": "Runs Large"
        }
      ]
    }
  ]
}

For the "Fit" subdimension, the "id" is one of: 2 (Runs Small), 3 (True to Size), or 4 (Runs Large).

For range subdimensions (type 2), the average (1.21, in the example) is the average of the sort values. The average is based on the average value of the "Fit" subdimension for the number of published reviews. In other words, the fit is close to "True to Size" but a little on the "Runs Large" side. With this information, you can display the average value along the range line.

To calculate the percentage instead of the average value, divide the average (1.21) by the max sortOrder value for the dimension (2), which in this example equals 60%.

Additional API reference documentation: Products.

Creating reviews

POST https://api.turnto.com/v1.3/reviews

Using the data collected from pulling subdimensions for a SKU, this is the JSON string example with subdimension ID of 3 (True to Size) to be used within the Create Review API endpoint.

JSON 
{
    "rating": 5,
    "title": "I love my shirt",
    "text": "This shirt fits great and is made of super soft material.",
    "user": {
        "nickName": "Superman",
        "firstName": "Clark",
        "lastName": "Kent",
        "emailAddress": "mindmanneredreporter@example.com"
    },
    "catalogItems": [
        {
            "sku": "shirt1"
        }
    ],
    "dimensions": [
        {
            "value": 3
        }
    ]
}

Additional API reference documentation: Create Review.

Attaching images with the Create Review endpoint

The Emplifi API accepts these image types:

  • image/jpeg

  • image/jpg

  • image/pjpeg

  • image/png

  • image/x-png

The max allowable image size is 10 MB per image. The max number of images is 5 images per review.

Images are sent as Base64 binary encoded data. In other words, the image is encoded and included in the body of the API request.

Additional API reference documentation: Create Review.

Displaying images with the Review List endpoint

The Review List endpoint returns three image URLs in the response: originalUrl, normalUrl, and thumbnailUrl. Please use thumbnailUrl in the review list because it's the smallest image and will perform best on your page.

You may want to have an onClick event on the image to pull the normalUrl to show detail. This normalUrl image is also included in the Review Detail endpoint.

Additional API reference documentation: Review List and Review Detail.

Creating a Review Summary section and Review Teaser

The UGC summary is a collection of data points for a particular catalog item, such as number of questions, number of reviews, and average rating.

GET https://api.turnto.com/v1.3/products/ugc_summary?sku=<SKU>

Example:

GET https://api.turnto.com/v1.3/products/ugc_summary?sku=shirt1

Additional API reference documentation: UGC Summary.

Listing reviews

This endpoint returns a list of reviews associated with a catalog item. The catalog item is identified by the sku parameter. You can retrieve direct reviews, related reviews, or a combined list containing both. Direct reviews are reviews that were created for a catalog item. Related reviews are reviews that are related to a catalog item, either as Virtual Parent Siblings, or as bundle parents.

Additional API reference documentation: Review List.

Listing only direct reviews

GET https://api.turnto.com/v1.3/reviews?sku=<SKU>

Example:

GET https://api.turnto.com/v1.3/reviews?sku=shirt1

Listing only related reviews

This assumes the catalog feed you send Emplifi includes variant SKUs related by a virtual parent. You could use this endpoint to create a "related reviews" section on your product page.

GET https://api.turnto.com/v1.3/reviews?sku=<SKU>&related=true

Example:

GET https://api.turnto.com/v1.3/reviews?sku=shirt1&related=true

Listing all direct and related reviews

This assumes the catalog feed you send Emplifi includes variant SKUs related by a virtual parent.

GET https://api.turnto.com/v1.3/reviews?sku=<SKU>&includeRelated=true

Example:

GET https://api.turnto.com/v1.3/reviews?sku=shirt1&includeRelated=true

Retrieving review details

Get details for a specific review.

GET https://api.turnto.com/v1.3/reviews/<REVIEW ID>

Additional API reference documentation: Review Detail.

Retrieving filtered reviews by star-rating

The filter parameter provides the ability to drill down into review results. The natural logic of filter keywords is OR. For example, rating(4,5) means reviews with a star rating of 4 or 5. Use an exclamation point to negate filter keywords. For example, !rating(1) means reviews that do not have a star rating of 1.

GET https://api.turnto.com/v1.3/reviews?sku=<SKU>&includeFilters=true&filter=rating(<STAR RATING VALUES>)

Example:

GET https://api.turnto.com/v1.3/reviews?sku=shirt1&includeFilters=true&filter=rating(4,5)

Additional API reference documentation: Review List.

Paginating reviews

You can paginate the reviews listing by using the limit and offset parameters.

GET https://api.turnto.com/v1.3/reviews?sku=<SKU>&limit=<NUMBER TO RETRIEVE>&offset=<NUMBER TO START AT>

These examples assume you are showing 10 reviews per page (limit=10 parameter).

Retrieve the first 10 reviews.

GET https://api.turnto.com/v1.3/reviews?sku=shirt1&limit=10&offset=0

Retrieve the next 10 reviews.

GET https://api.turnto.com/v1.3/reviews?sku=shirt1&limit=10&offset=10

Retrieve the next 10 reviews, etc, etc.

GET https://api.turnto.com/v1.3/reviews?sku=shirt1&limit=10&offset=20

Additional API reference documentation: Review List.

Upvoting a review

Register an up vote for a review with this endpoint.

POST https://api.turnto.com/v1.3/reviews/<REVIEW ID>/voteup

Additional API reference documentation: Review Vote Up.

Downvoting a review

Register a down vote for a review with this endpoint.

POST https://api.turnto.com/v1.3/reviews/<REVIEW ID>/votedown

Additional API reference documentation: Review Vote Down.

Flagging a review

Flag a review as inappropriate with this endpoint.

POST https://api.turnto.com/v1.3/reviews/<REVIEW ID>/flag

Additional API reference documentation: Flag Review.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close