Reviews API

The Reviews API returns your collected reviews for a specific client configuration. The format is similar to the public JSON Display API. Both published and non-published reviews are included.

Different Types of Product Reviews

TestFreaks handles three different types of product reviews: expert reviews, user reviews, and customer reviews.

The Reviews API only handles customer reviews, reviews written by your own customers about a specific product.

Note The Reviews API can not be used to retrieve or manage external reviews (expert reviews and user reviews).

GET /v1/reviews

Lists reviews matching the request parameters and provides a next page link if the result spans multiple pages.

It is possible to use this API endpoint to incrementally fetch and synchronize all reviews from the API.

Request parameters

limit, how many reviews per page, default 100, maximum 1000

client_id, the unique identifier for your client configuration.

updated_after (optional) set to YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ (ISO 8601) to filter reviews on updated timestamp. For example, 2021-10-01T13:00:00Z

created_after (optional) set to YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ (ISO-8601) to filter reviews on created timestamp. For example, 2021-10-01T13:00:00Z

order_id (optional) for filtering reviews on a specific Order ID

customer_id (optional) for filtering reviews on a specific Customer ID

after, used for pagination

Response body

See below, and see the separate description of fields.

If .links.next is set, additional pages are available by following the link.

If .errors is set, it’s a list of errors.

Example

$ curl -u sk_token: https://api.testfreaks.com/v1/reviews?client_id=example.com
{
  "data": [
    {
      "id": "e63b2ad38dd9ada0",
      "type": "customer",
      "author": "John D",
      "score": 4,
      "score_max": 5,
      "date": "2021-11-22",
      "extract": "Great product",
      "pros": [
        "pro1",
        "pro2"
      ],
      "cons": [],
      "lang": "en",
      "verified_buyer": true,
      "votes_up": 0,
      "votes_down": 0,
      "product": "Product name",
      "responses": [],
      "images": [
        {
          "token": "43b1c28cea4f74e57701edf25ad4b671",
          "format": "jpeg",
          "width": 3840,
          "height": 2160,
          "icon": "<url>",
          "icon_width": 100,
          "icon_height": 100,
          "medium": "<url>",
          "medium_width": 1600,
          "medium_height": 900,
          "large": "<url>",
          "large_width": 3840,
          "large_height": 2160
        }
      ],
      "properties": {},
      "family_ids": [
        "P001"
      ],
      "product_ids": [
        "P001-02-BLK"
      ],
      "order_id": "O123",
      "customer_id": "C001",
      "updated_at": "2021-11-22T06:38:04Z",
      "accepted": true,
      "accepted_at": "2021-11-22T08:31:46Z",
      "verified_email": true,
      "author_email": "john.doe@example.com",
      "portal_url": "https://reviews.testfreaks.com/portal/reviews/e63b2ad38dd9ada0?client_id=your.client.id"
    }
  ],
  "links": {
    "next": "https://api.testfreaks.com/v1/reviews?after=123123429"
  }
}

Pros & Cons

In order to match the data format for POST/PUT, pros and cons are returned as lists instead of as combined texts as in the public JSON Display API.

Images

Images contain additional fields as provided by the image API.

images.token Image token
images.format Image format string
images.width Original image width
images.height Original image height

GET /v1/reviews/<review-id>

Returns a single review based on its review ID.

Uses the same format as list reviews above except that it only returns a single object.

$ curl -u sk_token: https://api.testfreaks.com/v1/reviews/e63b2ad38dd9ada0?client_id=example.com

POST /v1/reviews

Creates a new review from the data in the JSON request body.

Request parameters

client_id, the unique identifier for your client configuration.

Request body

Set the Content-Type to application/json and post review data using the following structure:

{
  "review": {
    "external_id": "R001",
    "order": {
      "id": "O123",
      "customer": {
        "id": "C001",
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "item": {
        "id": "P001-02-BLK",
        "family_id": "P001"
      }
    },
    "author": "John D",
    "score": 4,
    "date": "2022-10-01",
    "extract": "Review content",
    "pros": ["pro1", "pro2"],
    "cons": ["con1"],
    "images": [
      {
        "token": "43b1c28cea4f74e57701edf25ad4b671",
        "format": "jpeg",
        "width": 3840,
        "height": 2160
      }
    ],
    "custom_questions": {
      "fit": "small",
      "activity": ["running", "hiking", "climbing"]
    },
    "accepted": true
  }
}

external_id (optional) can be used to provide a pre-existing review ID. Specifying an external_id that already exist will update that review rather than creating a new review.

order specifies the order details (including customer and product information) as per the v1/orders API but limited to a single order item.

author is the public author name.

score is the review score 1-5.

date (optional) is the review date for importing pre-existing reviews.

extract (optional) is the review content, limited to 60000 characters.

pros and cons (optional) are the individual positives/negatives. Limited to 2000 characters each.

images (optional) is a list of image objects where each object is the result from uploading an image to the image API.

custom_questions (optional) is a collection of question names and answer values. Depending on the client configuration this could be either a single string or an array of strings for each question.

accepted (optional) overrides the manual moderation process. true marks the review as approved. false marks the review as rejected. null resets the moderation status to the default for a new review, allowing the system to decide how to handle moderation.

Response body

Returns the posted review data or a list of errors if the request was unsuccessful. See the response format for the review listing above.

PUT /v1/reviews/<review-id>

Updates a single review based on its review ID.

Uses the same JSON body as in the POST above.

DELETE /v1/reviews/<review-id>

Deletes a review based on its review ID.

Incremental fetching of reviews

It is possible to incrementally fetch and synchronize all reviews from the API into e.g. a database on your side.

The outline of the process looks like this:

Feel free to reach out to us if you need any assistance or want to discuss different approaches.

Fetch all reviews

Fetch all reviews through GET /v1/reviews and save to your database. Don’t forget to follow any pagination links available in .links.next.

Fetch updated reviews

Fetch all updated reviews using GET /v1/reviews by setting update_after to a time, and save the fetched reviews to your database.

You can set update_after to one of the following:

  • The last time you started fetching reviews, or
  • The most recent updated_at value for any review you have seen during the last time you fetched reviews.

Picking a less recent (older) time is always safe. Picking a more recent (newer) time increases the risk of missing reviews.

If you get a Review ID (.data.id) from the API that you have already seen, you can either replace or update this review in your database.

The suggested interval to fetch updated reviews is daily. Note that the interval depends on your use case.

Fetch all reviews again

Fetch all reviews through GET /v1/reviews on a regular basis.

Sometimes it is important that your database contains only reviews that currently exist in the API. In this case you need to delete any review from your database that is not included in the reviews fetched from the API.

The suggested interval to fetch all reviews is once a week.

Fetching all reviews more frequently will make it possible to delete reviews that no longer exist in the API more quickly, but will also use more resources.