Go To Top

Product Reviews API

Create a new comment for a given conversation. The comment is appended to the list of existing comments.

POST
https://api.trustpilot.com/v1/private/conversations/{conversationId}/comments
Parameters
conversationId, Required String
The ID of the conversation to create a comment for
Example: …/v1/private/conversations/507f191e810c19729de860ea/comments

Request
{
  "content": "Thank you for you kind words, we really appreciate it.",
  "integrationId": "IB2478HFAJKN38"
}
Response
{
  "commentId": "507f191e810c19729de860ea",
  "createdAt": "2013-09-07T13:37:00",
  "author": {
    "id": "507f191e810c19729de860ea",
    "type": "businessUser"
  },
  "content": "Thank you for you kind words, we really appreciate it."
}

Prepares the review for participating in a conversation by issuing a conversation ID.

POST
https://api.trustpilot.com/v1/private/product-reviews/{reviewId}/create-conversation
Parameters
reviewId, Required String
The id of the product review
Example: …/v1/private/product-reviews/507f191e810c19729de860ea/create-conversation

Response
{
  "conversationId": "507f191e810c19729de860ea"
}

Given information about the consumer and the product(s) purchased, get a link that can be sent to the consumer to request reviews. Note that the products should either be specified as product ids (see the Product API) or as a product with product details. It is only possible to use one of these methods for specifying product information.

POST
https://api.trustpilot.com/v1/private/product-reviews/business-units/{businessUnitId}/invitation-links
Parameters
businessUnitId, Required String

Example: …/v1/private/product-reviews/business-units/{businessUnitId}/invitation-links

Request
{
  "consumer": {
    "email": "johndoe@somewhere.com",
    "name": "John Doe"
  },
  "referenceId": "123ABC",
  "locale": "en-US",
  "redirectUri": "https://www.example.com",
  "products": [
    {
      "productUrl": "http://www.mycompanystore.com/products/12345.htm",
      "imageUrl": "http://www.mycompanystore.com/products/images/12345.jpg",
      "name": "Metal Toy Car",
      "sku": "ABC-1234",
      "gtin": "01234567890",
      "mpn": "7TX1641",
      "brand": "Acme"
    }
  ],
  "productIds": [
    "507f191e810c19729de860ea",
    "507f191e810c19729de860eb",
    "507f191e810c19729de860ec"
  ]
}
Response
{
  "reviewLinkId": "d9339202586bf5f39200f605f09ccd90",
  "reviewUrl": "https://products.trustpilot.com/evaluate/d9339202586bf5f39200f605f09ccd90"
}

Get summaries of product reviews for multiple SKUs. The summaries contain information about stars average, distribution and count.

POST
Authentication: API Key
https://api.trustpilot.com/v1/product-reviews/business-units/{businessUnitId}/batch-summaries
Parameters
businessUnitId, Required String
The id of the business unit.
Example: …/v1/product-reviews/business-units/507f191e810c19729de860ea/batch-summaries

Request
{
  "skus": [
    "ABCD-1234",
    "ACDC-4321"
  ]
}
Response
{
  "summaries": [
    {
      "sku": "ABCD-1234",
      "numberOfReviews": {
        "total": 14,
        "oneStar": 2,
        "twoStars": 3,
        "threeStars": 2,
        "fourStars": 5,
        "fiveStars": 2
      },
      "starsAverage": 3.1
    }
  ]
}

Get a single comment by id.

GET
https://api.trustpilot.com/v1/private/conversations/{conversationId}/comments/{commentId}
Parameters
conversationId, Required String
The ID of the conversation the comment to retrieve is part of
Example: …/v1/private/conversations/507f191e810c19729de860ea/comments/{commentId}

commentId, Required String
The ID of the comment to retrieve
Example: …/v1/private/conversations/{conversationId}/comments/507f191e810c19729de860ea

Response
{
  "commentId": "507f191e810c19729de860ea",
  "createdAt": "2013-09-07T13:37:00",
  "author": {
    "id": "507f191e810c19729de860ea",
    "type": "businessUser"
  },
  "content": "Thank you for you kind words, we really appreciate it."
}

Get a conversation and related comments by id.

GET
https://api.trustpilot.com/v1/private/conversations/{conversationId}
Parameters
conversationId, Required String
The ID of the conversation to retrieve
Example: …/v1/private/conversations/507f191e810c19729de860ea

Response
{
  "id": "507f191e810c19729de860ea",
  "businessUnitId": "507f191e810c19729de860ea",
  "consumerId": "507f191e810c19729de860ea",
  "source": "Product reviews",
  "sourceId": "507f191e810c19729de860ea",
  "state": "public",
  "comments": [
    {
      "commentId": "507f191e810c19729de860ea",
      "createdAt": "2013-09-07T13:37:00",
      "author": {
        "id": "507f191e810c19729de860ea",
        "type": "businessUser"
      },
      "content": "Thank you for you kind words, we really appreciate it."
    }
  ]
}

This method allows you to get imported product reviews by business unit id, SKUs and language. It includes review content, date of creation of review, individual star rating and display name of the consumer who wrote the review. It is possible to paginate the results.

GET
Authentication: API Key
https://api.trustpilot.com/v1/product-reviews/business-units/{businessUnitId}/imported-reviews
Parameters
businessUnitId, Required String

Example: …/v1/product-reviews/business-units/507f191e810c19729de860ea/imported-reviews

page, Optional Integer
The page to retrieve. If the page number requested is higher than the available number of pages an empty array will be returned.
Constraints: The allowed range is minimum: 1, maximum: 2147483647
Default value: 1
Example: ?page=1

perPage, Optional Integer
The number of reviews to retrieve per page.
Constraints: The allowed range is minimum: 1, maximum: 100
Default value: 20
Example: ?perPage=3

sku, Required Array
The sku of the product.
Example: ?sku=ABCD-1234
* provide multiple values using comma seperation

stars, Optional Array
Star ratings to search for
Constraints: The allowed range is minimum: 1, maximum: 5
Example: ?stars=4
* provide multiple values using comma seperation

language, Optional String
Filter reviews by language.
Example: ?language=en

Response
{
  "productReviews": [
    {
      "createdAt": "2013-09-07T13:37:00",
      "stars": 4,
      "content": "This product was nice, but slightly too soft.",
      "consumer": {
        "name": "John Doe"
      },
      "language": "en"
    }
  ],
  "links": [
    {
      "href": "<Url for the resource>",
      "method": "<Http method for the resource>",
      "rel": "<Description of the relation>"
    }
  ]
}

Get a summary of imported product reviews for a single or multiple SKUs. The summary contains information about stars average, distribution and count.

GET
Authentication: API Key
https://api.trustpilot.com/v1/product-reviews/business-units/{businessUnitId}/imported-reviews-summaries
Parameters
businessUnitId, Required String
The id of the business unit.
Example: …/v1/product-reviews/business-units/507f191e810c19729de860ea/imported-reviews-summaries

sku, Required Array
The SKU of the product, or multiple comma-separated SKUs (which will be summarized together).
Example: ?sku=ABCD-1234
* provide multiple values using comma seperation

Response
{
  "links": [
    {
      "href": "<Url for the resource>",
      "method": "<Http method for the resource>",
      "rel": "<Description of the relation>"
    }
  ],
  "numberOfReviews": {
    "total": 14,
    "oneStar": 2,
    "twoStars": 3,
    "threeStars": 2,
    "fourStars": 5,
    "fiveStars": 2
  },
  "starsAverage": 3.1
}

Gets a single private product review. This method includes private information such as consumer e-mail and reference id.

GET
https://api.trustpilot.com/v1/private/product-reviews/{reviewId}
Parameters
reviewId, Required String
The id of the product review
Example: …/v1/private/product-reviews/507f191e810c19729de860ea

locale, Optional String
The language in which the attributes, if any, are returned
Default value: en-US
Example: ?locale=da-DK

Response
{
  "id": "507f191e810c19729de860ea",
  "createdAt": "2013-09-07T13:37:00",
  "updatedAt": "2013-09-07T13:37:00",
  "businessUnitId": "507f191e810c19729de860ea",
  "stars": 4,
  "content": "This product was nice, but slightly too soft.",
  "product": {
    "id": "507f191e810c19729de860ea",
    "productUrl": "http://www.mycompanystore.com/products/12345.htm",
    "productImages": [
      {
        "type": "100pxWide",
        "url": "http://www.mycompanystore.com/products/images/12345.jpg"
      }
    ],
    "name": "Metal Toy Car",
    "sku": "ABC-1234",
    "gtin": "01234567890",
    "mpn": "7TX1641",
    "brand": "Acme"
  },
  "consumer": {
    "id": "507f191e810c19729de860ea",
    "email": "johndoe@somewhere.com",
    "name": "John Doe"
  },
  "referenceId": "123ABC",
  "locale": "en-US",
  "language": "en",
  "redirectUri": "https://www.example.com",
  "state": "published",
  "hasModerationHistory": true,
  "conversationId": "507f191e810c19729de860ea",
  "attributeRatings": [
    {
      "attributeId": "attributes.default.quality",
      "attributeName": "Quality",
      "rating": 4
    }
  ],
  "attachments": [
    {
      "id": "507f191e810c19729de860ea",
      "state": "Published",
      "processedFiles": [
        {
          "dimension": "1024pxWide",
          "mimeType": "image/png",
          "url": "https://productreviews-attachments.trustpilot.com/507f191e810c19729de860ea_1024pxWide.png"
        }
      ]
    }
  ]
}

Given a list of SKUs or product urls return a list of product reviews. This method includes private information such as consumer e-mail and reference id. By default only published reviews are returned. To get reviews with other states, provide a list in the state field. Pagination is used to retrieve all results.

GET
https://api.trustpilot.com/v1/private/product-reviews/business-units/{businessUnitId}/reviews
Parameters
businessUnitId, Required String

Example: …/v1/private/product-reviews/business-units/5408d4b9065464000578ca81/reviews

page, Optional Integer
The page to retrieve. If the page number requested is higher than the available number of pages an empty array will be returned.
Constraints: The allowed range is minimum: 1, maximum: 2147483647
Default value: 1
Example: ?page=1

perPage, Optional Integer
The number of reviews to retrieve per page.
Constraints: The allowed range is minimum: 1, maximum: 100
Default value: 20
Example: ?perPage=3

sku, Optional Array
Filter reviews by product Stock-Keeping Unit (SKU) identifier
Example: ?sku=ABCD-1234
* provide multiple values using comma seperation

language, Optional String
Filter reviews by language.
Example: ?language=en

state, Optional Array
Which reviews to retrieve according to their review state. Default is Published.
Constraints: Allowed values are published, unpublished, underModeration, archived
Default value: [ "published" ]
Example: ?state=published
* provide multiple values using comma seperation

locale, Optional String
The language in which the attributes, if any, are returned
Default value: en-US
Example: ?locale=da-DK

Response
{
  "links": [
    {
      "href": "<Url for the resource>",
      "method": "<Http method for the resource>",
      "rel": "<Description of the relation>"
    }
  ],
  "productReviews": [
    {
      "id": "507f191e810c19729de860ea",
      "createdAt": "2013-09-07T13:37:00",
      "updatedAt": "2013-09-07T13:37:00",
      "businessUnitId": "507f191e810c19729de860ea",
      "stars": 4,
      "content": "This product was nice, but slightly too soft.",
      "product": {
        "id": "507f191e810c19729de860ea",
        "productUrl": "http://www.mycompanystore.com/products/12345.htm",
        "productImages": [
          {
            "type": "100pxWide",
            "url": "http://www.mycompanystore.com/products/images/12345.jpg"
          }
        ],
        "name": "Metal Toy Car",
        "sku": "ABC-1234",
        "gtin": "01234567890",
        "mpn": "7TX1641",
        "brand": "Acme"
      },
      "consumer": {
        "id": "507f191e810c19729de860ea",
        "email": "johndoe@somewhere.com",
        "name": "John Doe"
      },
      "referenceId": "123ABC",
      "locale": "en-US",
      "language": "en",
      "redirectUri": "https://www.example.com",
      "state": "published",
      "hasModerationHistory": true,
      "conversationId": "507f191e810c19729de860ea",
      "attributeRatings": [
        {
          "attributeId": "attributes.default.quality",
          "attributeName": "Quality",
          "rating": 4
        }
      ],
      "attachments": [
        {
          "id": "507f191e810c19729de860ea",
          "state": "Published",
          "processedFiles": [
            {
              "dimension": "1024pxWide",
              "mimeType": "image/png",
              "url": "https://productreviews-attachments.trustpilot.com/507f191e810c19729de860ea_1024pxWide.png"
            }
          ]
        }
      ]
    }
  ],
  "total": 0
}

This method allows you to get business unit product reviews for SKUs and / or productUrls. Note: Even though productUrl and sku are listed as optional parameters at least one of them must be specified. It includes review content, date of creation of review, individual star rating, id and display name of the consumer who wrote the review. Pagination and filtering reviews by language is also possible.

GET
Authentication: API Key
https://api.trustpilot.com/v1/product-reviews/business-units/{businessUnitId}/reviews
Parameters
businessUnitId, Required String

Example: …/v1/product-reviews/business-units/5408d4b9065464000578ca81/reviews

page, Optional Integer
The page to retrieve. If the page number requested is higher than the available number of pages an empty array will be returned.
Constraints: The allowed range is minimum: 1, maximum: 2147483647
Default value: 1
Example: ?page=1

perPage, Optional Integer
The number of reviews to retrieve per page.
Constraints: The allowed range is minimum: 1, maximum: 100
Default value: 20
Example: ?perPage=3

productUrl, Optional Array
The url of the product. Optional only if sku is provided.
Example: ?productUrl=http%3A%2F%2Fwww.mycompanystore.com%2Fproducts%2Fimages%2F12345.jpg
* provide multiple values using comma seperation

sku, Optional Array
The sku of the product. Optional only if productUrl is provided.
Example: ?sku=ABCD-1234
* provide multiple values using comma seperation

language, Optional String
Filter reviews by language.
Example: ?language=en

stars, Optional Array
Filter reviews with a specific number of stars.
Constraints: Allowed values are 1, 2, 3, 4, 5
Example: ?stars=5
* provide multiple values using comma seperation

locale, Optional String
The language in which the attributes, if any, are returned
Default value: en-US
Example: ?locale=da-DK

attributeIds, Optional Array
A comma-separated list of attribute ids
Example: ?attributeIds=attributes.default.quality,attributes.default.value-for-money
* provide multiple values using comma seperation

Response
{
  "productReviews": [
    {
      "id": "507f191e810c19729de860ea",
      "createdAt": "2013-09-07T13:37:00",
      "stars": 4,
      "content": "This product was nice, but slightly too soft.",
      "consumer": {
        "id": "507f191e810c19729de860ea",
        "displayName": "John Doe"
      },
      "language": "en",
      "attributeRatings": [
        {
          "attributeId": "attributes.default.quality",
          "attributeName": "Quality",
          "rating": 4
        }
      ],
      "attachments": [
        {
          "id": "507f191e810c19729de860ea",
          "state": "Published",
          "processedFiles": [
            {
              "dimension": "1024pxWide",
              "mimeType": "image/png",
              "url": "https://productreviews-attachments.trustpilot.com/507f191e810c19729de860ea_1024pxWide.png"
            }
          ]
        }
      ]
    }
  ],
  "links": [
    {
      "href": "<Url for the resource>",
      "method": "<Http method for the resource>",
      "rel": "<Description of the relation>"
    }
  ]
}

Get a list of summaries of product reviews for a business unit. The summary contains information about stars average, distribution and count. Pagination is used to retrieve all results.

GET
https://api.trustpilot.com/v1/private/product-reviews/business-units/{businessUnitId}/summaries
Parameters
businessUnitId, Required String
The id of the business unit
Example: …/v1/private/product-reviews/business-units/507f191e810c19729de860ea/summaries

page, Optional Integer
The page to retrieve. If the page number requested is higher than the available number of pages an empty array will be returned.
Constraints: The allowed range is minimum: 1, maximum: 2147483647
Default value: 1
Example: ?page=1

perPage, Optional Integer
The number of summaries to retrieve per page.
Constraints: The allowed range is minimum: 1, maximum: 1000
Default value: 1000
Example: ?perPage=3

Response
{
  "links": [
    {
      "href": "<Url for the resource>",
      "method": "<Http method for the resource>",
      "rel": "<Description of the relation>"
    }
  ],
  "summaries": [
    {
      "sku": "ABC-1234",
      "starsAverage": 3.1,
      "numberOfReviews": {
        "total": 14,
        "oneStar": 2,
        "twoStars": 3,
        "threeStars": 2,
        "fourStars": 5,
        "fiveStars": 2
      }
    }
  ]
}

Get a summary of product reviews for a single or multiple SKU(s). The summary contains information about stars average, distribution and count.

GET
Authentication: API Key
https://api.trustpilot.com/v1/product-reviews/business-units/{businessUnitId}
Parameters
businessUnitId, Required String
The id of the business unit.
Example: …/v1/product-reviews/business-units/507f191e810c19729de860ea

sku, Required Array
A single or multiple comma-separated SKUs of the product(s).
Example: ?sku=ABCD-1234
* provide multiple values using comma seperation

Response
{
  "links": [
    {
      "href": "<Url for the resource>",
      "method": "<Http method for the resource>",
      "rel": "<Description of the relation>"
    }
  ],
  "numberOfReviews": {
    "total": 14,
    "oneStar": 2,
    "twoStars": 3,
    "threeStars": 2,
    "fourStars": 5,
    "fiveStars": 2
  },
  "starsAverage": 3.1
}

Get the aggregated attribute ratings for the provided SKUs for the business unit

POST
Authentication: API Key
https://api.trustpilot.com/v1/product-reviews/business-units/{businessUnitId}/attribute-summaries
Parameters
businessUnitId, Required String
The id of the business unit
Example: …/v1/product-reviews/business-units/507f191e810c19729de860ea/attribute-summaries

Request
{
  "skus": [
    "ABCD-1234",
    "ACDC-4321"
  ],
  "locale": "da-DK"
}
Response
{
  "summaries": [
    {
      "sku": null,
      "attributes": [
        {
          "id": "attributes.default.quality",
          "name": "Quality",
          "type": "range_1to5",
          "options": [
            null
          ],
          "totalOccurrences": 1234,
          "occurrences": {
            "one": 2,
            "two": 0,
            "three": 0,
            "four": 10,
            "five": 60
          },
          "average": 4.23
        }
      ]
    }
  ]
}

Get a public conversation and related comments by id.

GET
Authentication: API Key
https://api.trustpilot.com/v1/conversations/{conversationId}
Parameters
conversationId, Required String
The ID of the conversation to retrieve
Example: …/v1/conversations/507f191e810c19729de860ea

Response
{
  "id": "507f191e810c19729de860ea",
  "businessUnitId": "507f191e810c19729de860ea",
  "consumerId": "507f191e810c19729de860ea",
  "comments": [
    {
      "commentId": "507f191e810c19729de860ea",
      "createdAt": "2013-09-07T13:37:00",
      "author": {
        "id": "507f191e810c19729de860ea",
        "type": "businessUser"
      },
      "content": "Thank you for you kind words, we really appreciate it."
    }
  ]
}

Set the conversation state to either public or private. If set to private no third parties will see the conversation.

POST
https://api.trustpilot.com/v1/private/conversations/{conversationId}/state
Parameters
conversationId, Required String
The ID of the conversation to change the state for
Example: …/v1/private/conversations/507f191e810c19729de860ea/state

Request
{
  "state": "private"
}

Edit a single comment by id.

PUT
https://api.trustpilot.com/v1/private/conversations/{conversationId}/comments/{commentId}
Parameters
conversationId, Required String
The ID of the conversation to update a comment for
Example: …/v1/private/conversations/507f191e810c19729de860ea/comments/{commentId}

commentId, Required String
The ID of the comment to update
Example: …/v1/private/conversations/{conversationId}/comments/507f191e810c19729de860ea

Request
{
  "content": "Thank you for you kind words, we really appreciate it.",
  "integrationId": "IB2478HFAJKN38"
}
Response
{
  "commentId": "507f191e810c19729de860ea",
  "createdAt": "2013-09-07T13:37:00",
  "author": {
    "id": "507f191e810c19729de860ea",
    "type": "businessUser"
  },
  "content": "Thank you for you kind words, we really appreciate it."
}