The data returned from a reviews API call is described in the following table. For documentation purposes, the format of each parameter has been abbreviated to the form reviews.<parameter_name>.<parameter_name> whereas in fact the data would be presented in a similar format to the following example:
https://api.feefo.com/api/version/reviews/all?merchant_identifier=example-retail-merchantThis API call would produce the following review data from Feefo (for brevity, only a single customer review consisting of service feedback and two sets of product feedback is displayed below):
{ "summary": { "meta": { "count": 3878, "pages": 194, "page_size": 20, "current_page": 1 } }, "reviews": [ { "merchant": { "identifier": "example-retail-merchant" }, "url": "http://www.feefo.com/en_GB/reviews/example-retail-merchant/572f69dd498ee99ed9348e49/customer-review-fab-as-usual", "social": { "facebook": "http://www.facebook.com/dialog/share?app_id=88240596850xxxx&href=http%3A%2F%2Fwww.feefo.com%2Fen_GB%2Freviews%2Fexample-retail-merchant%2F572f69dd498ee99ed934xxxx%2Fcustomer-review-fab-as-usual&redirect_uri=http%3A%2F%2Fwww.fee.fo%2FyOrn22", "twitter": "http://twitter.com/intent/tweet?text=&url=http%3A%2F%2Fwww.fee.fo%2FyOrn22&via=Feefo_Official" }, "customer": { "display_name": "Emily" }, "service": { "rating": { "min": 1, "max": 5, "rating": 5 }, "id": "5733aab0498edc149d51xxxx", "title": "Fab as usual", "review": "Speedy deliver, easy to use website.", "created_at": 1463003823439, "helpful_votes": 0 }, "products": [ { "rating": { "min": 1, "max": 5, "rating": 5 }, "id": "5733aaaf498edc149d51xxxx", "review": "Gorgeous scarf, so nice I wanted to keep it myself rather than give it for a gift.", "product": { "title": "White and Black Stripped Scarf", "sku": "1234", "url": "http://www.exampleretailmerchant.co.uk/white-and-black-stripped-scarf", "reviews_url": "http://www.feefo.com/en_GB/reviews/example-retail-merchant/products/white-and-black-stripped-scarf?sku=1234" }, "created_at": 1463003823983, "helpful_votes": 0 }, { "rating": { "min": 1, "max": 5, "rating": 5 }, "id": "5733aab0498edc149d51726b", "review": "Smells gorgeous & a the recipe is attached.", "product": { "title": "Strawberry Cheesecake Candle", "sku": "12345", "url": "http://www.exampleretailmerchant.co.uk/strawberry-cheescake-candle", "reviews_url": "http://www.feefo.com/en_GB/reviews/example-retail-merchant/products/strawberry-cheesecake-candle?sku=12345" }, "created_at": 1463003824282, "helpful_votes": 0 } ] }, ] }
Note that any parameter listed in the table with square brackets [] could have an array/multiple results. For example, reviews[].service.custom[] indicates there may be multiple reviews, each of which will have just one service review within which there may be multiple custom question responses.
Response parameter | Modes | Description | Authent-ication required |
summary.meta.count | all, service, product, nps | The total number of matching sales corresponding to the feedback result set. | No |
summary.meta.pages | all, service, product, nps | The number of pages of results available. | No |
summary.meta.page_size | all, service, product, nps | The number of results per page. | No |
summary.meta.current_page | all, service, product, nps | The current page of results being returned. | No |
reviews[].merchant.identifier | all, service, product, nps | The merchant identifier the feedback relates to. Suppressed when include_children = false. | No |
reviews[].last_updated_date | all, service, product, nps | The UTC date/time the customer’s review was last updated. | No |
reviews[].products_purchased[] | all, service, product, nps | The title of all products associated with the sale (including those which have not received feedback). | No |
reviews[].tags[].key | all, service, product, nps | The key of the sale tag associated with the feedback. | Yes |
reviews[].tags[].values[] | all, service, product, nps | The value of the sale tag associated with the feedback, there may be multiple values corresponding to the specified key. | Yes |
reviews[].tags[].type | all, service, product, nps | The type of tag associated with the feedback:
| Yes |
reviews[].url | all, service, product | The URL of the review on Feefo’s site. | No |
reviews[].social.facebook | all, service, product | The URL of the Facebook share link for the review. | No |
reviews[].social.twitter | all, service, product | The URL of the Twitter share link for the review. | No |
reviews[].social.google_plus | all, service, product | The URL of the Google+ share link for the review. | No |
reviews[].customer.display_name | all, service, product | The name the customer has provided to share alongside the review. Where the customer has opted out of displaying their identity this value will be omitted. | No |
reviews[].customer.display_location | all, service, product | The location the customer has provided to share alongside the review. Where the customer has opted out of displaying their identity this value will be omitted. | No |
reviews[].customer.name | all, service, product, nps | The name of the customer as provided in the original sale upload | Yes |
reviews[].customer.email | all, service, product, nps | The email address of the customer as provided in the original sale upload | Yes |
reviews[].customer.mobile | all, service, product, nps | The mobile phone number of the customer as provided in the original sale upload | Yes |
reviews[].customer.order_ref | all, service, product, nps | The order reference associated with the feedback | Yes |
reviews[].customer.customer_ref | all, service, product, nps | The customer reference associated with the feedback. This will only be included where there is an associated customer reference. | Yes |
reviews[].service.rating.min | all, service | The lowest possible Feefo rating. The default is 1.0. | No |
reviews[].service.rating.max | all, service | The highest possible Feefo rating. The default is 5.0. | No |
reviews[].service.rating.rating | all, service | The service rating assigned to the feedback, between 1 and 5. Where the customer has re-rated their feedback the most recent rating assigned will be returned. | No |
reviews[].service.id | all, service | The feedback id for the service review element. | No |
reviews[].service.created_at | all, service | The UTC date/time the service feedback was created. | No |
reviews[].service.title | all, service | The title assigned to the service feedback. Where the customer has chosen not to provide a title this will be omitted. | No |
reviews[].service.review | all, service | The customer’s original review of the merchant’s service. | No |
reviews[].service.helpful_votes | all, service | The number of helpful votes the service feedback has received. | No |
reviews[].service.media[].id | all, service | The Object ID of the media item. | No |
reviews[].service.media[].type | all, service | The type of media attached to the service feedback (photo/video). | No |
reviews[].service.media[].url | all, service | The URL to the media item. | No |
reviews[].service.media[].thumbnail | all, service | The URL to the video static thumbnail. Only present for type = video. | No |
reviews[].service.media[].caption | all, service | The consumer-provided caption for the media item. | No |
reviews[].service.media[].helpful_votes | all, service | The number of helpful votes the service media item has received. | No |
reviews[].service.custom[].question_id | all, service | The unique ID of the custom service question. | Yes |
reviews[].service.custom[].question | all, service | The title of the custom service question. This is only included if the customer provided a response to the question. | Yes |
reviews[].service.custom[].answer | all, service | The response to the custom service question. This is only included if the customer provided a response to the question. | Yes |
reviews[].service.sentiment.features[].text | all, service | Only included if the account has Smart Themes enabled and enhanced_insight = include. The text of any features associated with the service review in order of sentiment score, highest to lowest. | No |
reviews[].service.sentiment.features[].score | all, service | Only included if the account has Smart Themes enabled and enhanced_insight = include. The sentiment score between -1 and +1 of any features associated with the service review in order of sentiment score, highest to lowest. | No |
reviews[].service.sentiment.positive_snippets[].text | all, service | Only included if the account has Smart Themes enabled and enhanced_insight = include. A list of the positively categorised snippets associated with the service review ordered by sentiment score, highest to lowest. | No |
reviews[].service.sentiment.positive_snippets[].score | all, service | Only included if the account has Smart Themes enabled and enhanced_insight = include. The sentiment score between -1 and +1 of the positively categorised snippets associated with the service review ordered by sentiment score, highest to lowest. | No |
reviews[].service.sentiment.negative_snippets[].text | all, service | Only included if the account has Smart Themes enabled and enhanced_insight = include. A list of the negatively categorised snippets associated with the service review ordered by sentiment score, lowest to highest. | No |
reviews[].service.sentiment.negative_snippets[].score | all, service | Only included if the account has Smart Themes enabled and enhanced_insight = include. The sentiment score between -1 and +1 of the negatively categorised snippets associated with the service review ordered by sentiment score, lowest to highest. | No |
reviews[].service.thread[].created_at | all, service | The UTC date/time the thread entry was created. | No |
reviews[].service.thread[].type | all, service | The type of thread entry:
| No |
reviews[].service.thread[].author | all, service | The display name of the person who created the thread entry. | No |
reviews[].service.thread[].comment | all, service | The comment corresponding to the thread entry. This will be absent for customer_rerate. | No |
reviews[].service.thread[].old_rating | all, service | The previous service rating assigned by the consumer, between 1 and 5. Only present for customer_rerate (between 1 and 5). | No |
reviews[].service.thread[].new_rating | all, service | The new service rating assigned by the consumer, between 1 and 5. Only present for customer_rerate (between 1 and 5). | No |
reviews[].service.thread[].old_title | all, service | The old review title. Only present for reviews[].service.thread[].type = customer_retitle.
| No |
reviews[].service.thread[].new_title | all, service | The new review title. Only present for reviews[].service.thread[].type = customer_retitle.
| No |
reviews[].products[].product.title | all, product | The title of the product which has been reviewed. | No |
reviews[].products[].product.parent_sku | all, product | The parent SKU assigned to the product. This will only be displayed where a value has been assigned. | No |
reviews[].products[].product.sku | all, product | The SKU assigned to the product. | No |
reviews[].products[].product.tags[].key | all, product | The key of the product tag associated with the product feedback. | Yes |
reviews[].products[].product.tags[].values[] | all, product | The value of the product tag associated with the product feedback. There may be multiple values associated with the specified key. | Yes |
reviews[].products[].product.tags[].type | all, product | The type of tag associated with the feedback:
| Yes |
reviews[].products[].product.url | all, product | The URL of the product on the merchant’s website. In order of preference the following URL will be returned:
| No |
reviews[].products[].product.reviews_url | all, product | The URL for all reviews for the product on Feefo’s website in the form:
| No |
reviews[].products[].product.image_url | all, product | The URL of the product image stored by Feefo, as uploaded via the product catalogue. Where an image is unavailable this will be omitted. | No |
reviews[].products[].rating.min | all, product | The lowest possible Feefo rating. The default is 1.0. | No |
reviews[].products[].rating.max | all, product | The highest possible Feefo rating. The default is 5.0. | No |
reviews[].products[].rating.rating | all, product | The product rating assigned to the feedback, between 1 and 5. Where the customer has re-rated their feedback the most recent rating assigned will be returned. | No |
reviews[].products[].attributes[].name | all, product | The name of the product attribute which has been rated. | No |
reviews[].products[].attributes[].min | all, product | The minimum rating which could have been assigned to the attribute. The default is 1.0. | No |
reviews[].products[].attributes[].max | all, product | The maximum rating which could have been assigned to the attribute. The default is 5.0. | No |
reviews[].products[].attributes[].rating | all, product | The rating which has been assigned to the attribute, between 1 and 5. | No |
reviews[].products[].id | all, product | The feedback id for the product review element. | No |
reviews[].products[].created_at | all, product | The UTC date/time the product feedback was created. | No |
reviews[].products[].review | all, product | The customer’s original review of the product. | No |
reviews[].products[].helpful_votes | all, product | The number of helpful votes the product feedback has received. | No |
reviews[].products[].media[].id | all, product | The Object ID of the media item. | No |
reviews[].products[].media[].type | all, product | The type of media attached to the product feedback:
| No |
reviews[].products[].media[].url | all, product | The URL to the media item. | No
|
reviews[].products[].media[].thumbnail | all, product | The URL to the video static thumbnail. Only present for type = video. | No
|
reviews[].products[].media[].caption | all, product | The consumer provided caption for the media item. | No |
reviews[].products[].media[].helpful_votes | all, product | The number of helpful votes the product media item has received. | No |
reviews[].products[].media[].social.facebook | all, product | The URL of the Facebook share link for the review. | No |
reviews[].products[].media[].social.twitter | all, product | The URL of the Twitter share link for the review. | No |
reviews[].products[].media[].social.google_plus | all, product | The URL of the Google+ share link for the review. | No |
reviews[].products[].custom[].question | all, product | The title of the custom product question. This is only included if the customer provided a response to the question. | Yes |
reviews[].products[].custom[].answer | all, product | The response to the custom product question. This is only included if the customer provided a response to the question. | Yes |
reviews[].products[].sentiment.features[].text | all, product | Only included if the account has Smart Themes enabled and enhanced_insight = include. The text of any features associated with the product review in order of sentiment score, highest to lowest. | No |
reviews[].products[].sentiment.features[].score | all, product | Only included if the account has Smart Themes enabled and enhanced_insight = include. The sentiment score between -1 and +1 of any features associated with the product review in order of sentiment score, highest to lowest. | No |
reviews[].products[].sentiment.positive_snippets[].text | all, product | Only included if the account has Smart Themes enabled and enhanced_insight = include. A list of the positively categorised snippets associated with the product review ordered by sentiment score, highest to lowest. | No |
reviews[].products[].sentiment.positive_snippets[].score | all, product | Only included if the account has Smart Themes enabled and enhanced_insight = include. The sentiment score between -1 and +1 of the positively categorised snippets associated with the product review ordered by sentiment score, highest to lowest. | No |
reviews[].products[].sentiment.negative_snippets[].text | all, product | Only included if the account has Smart Themes enabled and enhanced_insight = include. A list of the negatively categorised snippets associated with the product review ordered by sentiment score, lowest to highest. | No |
reviews[].products[].sentiment.negative_snippets[].score | all, product | Only included if the account has Smart Themes enabled and enhanced_insight = include. The sentiment score between -1 and +1 of the negatively categorised snippets associated with the product review ordered by sentiment score, lowest to highest. | No |
reviews[].products[].thread[].created_at | all, product | The UTC date/time the thread entry was created. | No |
reviews[].products[].thread[].type | all, product | The type of thread entry:
| No |
reviews[].products[].thread[].author | all, product | The display name of the person who created the thread entry. | No |
reviews[].products[].thread[].comment | all, product | The comment corresponding to the thread entry. This will be absent for customer_rerate. | No |
reviews[].products[].thread[].old_rating | all, product | The previous service rating assigned by the consumer, between 1 and 5. Only present for customer_rerate (between 1 and 5). | No |
reviews[].products[].thread[].new_rating | all, product | The new service rating assigned by the consumer, between 1 and 5. Only present for customer_rerate (between 1 and 5). | No |
reviews[].products[].thread[].attributes[].name | all, product | The name of the attribute which has been rerated. Only present for reviews[].products[].thread[].type = customer_attribute_rerate.
| No |
reviews[].products[].thread[].attributes[].old_rating | all, product | The old attribute rating. Only present for reviews[].products[].thread[].type = customer_attribute_rerate (between 1 and 5). | No |
reviews[].products[].thread[].attributes[].new_rating | all, product | The new attribute rating. Only present for reviews[].products[].thread[].type = customer_attribute_rerate (between 1 and 5). | No |
reviews[].nps.created_at | all, nps | The UTC date/time the NPS feedback was created. | Yes |
reviews[].nps.rating | all, nps | The NPS rating the customer has assigned to the feedback, between 0 and 10. This will only be included where a rating has been provided. | Yes |
reviews[].nps.reason | all, nps | The reason the customer has provided to accompany their NPS rating. This will only be included where a reason has been provided. | Yes |