Introduction

The data returned from a reviews API call is described in the following table.

📘

Note

If you would like to manage your own display solution Feefo's Reviews API allows you to retrieve all the data you need.

This option is not suitable as a means of batch retrieving review content if you plan to self-host the data due to network edge caching. If you would like to self-host your review content please contact us to discuss the best options taking your requirements into consideration.

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-merchant

This 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

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 parameterModesDescriptionAuthentication required
summary.meta.countall, service, product, npsThe total number of matching sales corresponding to the feedback result set.No
summary.meta.pagesall, service, product, npsThe number of pages of results available.No
summary.meta.page_sizeall, service, product, npsThe number of results per page.No
summary.meta.current_pageall, service, product, npsThe current page of results being returned.No
reviews[].merchant.identifierall, service, product, npsThe merchant identifier the feedback relates to. Suppressed when include_children = false.No
reviews[].last_updated_dateall, service, product, npsThe UTC date/time the customer’s review was last updated.No
reviews[].products_purchased[]all, service, product, npsThe title of all products associated with the sale (including those which have not received feedback).No
reviews[].tags[].keyall, service, product, npsThe key of the sale tag associated with the feedback.Yes
reviews[].tags[].values[]all, service, product, npsThe value of the sale tag associated with the feedback, there may be multiple values corresponding to the specified key.Yes
reviews[].tags[].typeall, service, product, npsThe type of tag associated with the feedback:
sale – provided as part of the sale upload.feedback – applied via Insight Tags.
Yes
reviews[].urlall, service, productThe URL of the review on Feefo’s site.No
reviews[].social.facebookall, service, productThe URL of the Facebook share link for the review.No
reviews[].social.twitterall, service, productThe URL of the Twitter share link for the review.No
reviews[].social.google_plusall, service, productThe URL of the Google+ share link for the review.No
reviews[].customer.display_nameall, service, productThe name the customer has provided to share alongside the review. Where the customer has opted out of displaying their identity this value will be omittedNo
reviews[].customer.display_locationall, service, productThe 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.nameall, service, product, npsThe name of the customer as provided in the original sale upload.Yes
reviews[].customer.emailall, service, product, npsThe email address of the customer as provided in the original sale upload.Yes
reviews[].customer.mobileall, service, product, npsThe mobile phone number of the customer as provided in the original sale upload.Yes
reviews[].customer.order_refall, service, product, npsThe order reference associated with the feedback.Yes
reviews[].customer.customer_refall, service, product, npsThe customer reference associated with the feedback. This will only be included where there is an associated customer reference.Yes
reviews[].service.rating.minall, serviceThe lowest possible Feefo rating. The default is 1.0.No
reviews[].service.rating.maxall, serviceThe highest possible Feefo rating. The default is 5.0.No
reviews[].service.rating.ratingall, serviceThe 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.idall, serviceThe feedback id for the service review element.No
reviews[].service.created_atall, serviceThe UTC date/time the service feedback was created.No
reviews[].service.titleall, serviceThe title assigned to the service feedback. Where the customer has chosen not to provide a title this will be omitted.No
reviews[].service.reviewall, serviceThe customer’s original review of the merchant’s service.No
reviews[].service.helpful_votesall, serviceThe number of helpful votes the service feedback has received.No
reviews[].service.media[].idall, serviceThe Object ID of the media item.No
reviews[].service.media[].typall, serviceThe type of media attached to the service feedback (photo/video).No
reviews[].service.media[].urlall, serviceThe URL to the media item.No
reviews[].service.media[].thumbnailall, serviceThe URL to the video static thumbnail. Only present for type = video.No
reviews[].service.media[].captionall, serviceThe consumer-provided caption for the media item.No
reviews[].service.media[].helpful_votesall, serviceThe number of helpful votes the service media item has received.No
reviews[].service.custom[].question_idall, serviceThe unique ID of the custom service question.Yes
reviews[].service.custom[].questionall, serviceThe title of the custom service question. This is only included if the customer provided a response to the question.Yes
reviews[].service.custom[].answerall, serviceThe response to the custom service question. This is only included if the customer provided a response to the question.Yes
reviews[].service.sentiment.features[].textall, serviceOnly 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[].scoreall, serviceOnly 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[].textall, serviceOnly 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[].scoreall, serviceOnly 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[].textall, serviceOnly 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[].scoreall, serviceOnly 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_atall, serviceThe UTC date/time the thread entry was created.No
reviews[].service.thread[].typeall, serviceThe type of thread entry:
customer_comment – an additional comment made by the customer.
customer_rerate – an adjustment made to the service rating by the customer.
customer_retitle - an adjustment made to the service review title by the customer.
merchant_comment – a response from the merchant to the customer’s comments.
No
reviews[].service.thread[].authorall, serviceThe display name of the person who created the thread entry.No
reviews[].service.thread[].commentall, serviceThe comment corresponding to the thread entry. This will be absent for customer_rerate.No
reviews[].service.thread[].old_ratingall, serviceThe 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_ratingall, serviceThe 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_titleall, serviceThe old review title. Only present for reviews[].service.thread[].type = customer_retitle.No
reviews[].service.thread[].new_titleall, serviceThe new review title. Only present for reviews[].service.thread[].type = customer_retitle.No
reviews[].products[].product.titleall, productThe title of the product which has been reviewed.No
reviews[].products[].product.parent_skuall, productThe parent SKU assigned to the product. This will only be displayed where a value has been assigned.No
reviews[].products[].product.skuall, productThe SKU assigned to the product.No
reviews[].products[].product.tags[].keyall, productThe key of the product tag associated with the product feedback.Yes
reviews[].products[].product.tags[].values[]all, productThe 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[].typeall, productThe type of tag associated with the feedback:
product – provided as part of the sale upload, corresponds to the specific order line. feedback – applied via Insight Tags.
Yes
reviews[].products[].product.urlall, productThe URL of the product on the merchant’s website. In order of preference the following URL will be returned:
Product URL specified in an uploaded catalogue.
Product URL specified in the sales file.
URL specified as the product forwarding URL within merchant settings.
URL specified as the website forwarding URL within merchant settings.
No
reviews[].products[].product.reviews_urlall, productThe URL for all reviews for the product on Feefo’s website in the form:
http://www.feefo.com/locale/reviews/merchant-identifier/products/product-name?sku=product-sku
Where a parent product SKU has been provided the link will pass through the parent SKU.
No
reviews[].products[].product.image_urlall, productThe 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.minall, productThe lowest possible Feefo rating. The default is 1.0.No
reviews[].products[].rating.maxall, productThe highest possible Feefo rating. The default is 5.0.No
reviews[].products[].rating.ratingall, productThe 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[].nameall, productThe name of the product attribute which has been rated.No
reviews[].products[].attributes[].minall, productThe minimum rating which could have been assigned to the attribute. The default is 1.0.No
reviews[].products[].attributes[].maall, productThe maximum rating which could have been assigned to the attribute. The default is 5.0.No
reviews[].products[].attributes[].ratingall, productThe rating which has been assigned to the attribute, between 1 and 5.No
reviews[].products[].idall, productThe feedback id for the product review element.No
reviews[].products[].created_atall, productThe UTC date/time the product feedback was createdNo
reviews[].products[].reviewall, productThe customer’s original review of the product.No
reviews[].products[].helpful_votesall, productThe number of helpful votes the product feedback has received.No
reviews[].products[].media[].idall, productThe Object ID of the media item.No
reviews[].products[].media[].typeall, productThe type of media attached to the product feedback:
photo
video
No
reviews[].products[].media[].urlall, productThe URL to the media item.No
reviews[].products[].media[].thumbnailall, productThe URL to the video static thumbnail. Only present for type = video.No
reviews[].products[].media[].captionall, productThe consumer provided caption for the media item.No
reviews[].products[].media[].helpful_votesall, productThe number of helpful votes the product media item has received.No
reviews[].products[].media[].social.facebookall, productThe URL of the Facebook share link for the review.Np
reviews[].products[].media[].social.twitterall, productThe URL of the Twitter share link for the review.No
reviews[].products[].media[].social.google_plusall, productThe URL of the Google+ share link for the review.No
reviews[].products[].custom[].questionall, productThe title of the custom product question. This is only included if the customer provided a response to the question.Yes
reviews[].products[].custom[].answerall, productThe response to the custom product question. This is only included if the customer provided a response to the question.Yes
reviews[].products[].sentiment.features[].textall, productOnly 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[].scoreall, productOnly 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[].textall, productOnly 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[].scoreall, productOnly 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 lowes
No
reviews[].products[].sentiment.negative_snippets[].textall, productOnly 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[].scall, productOnly 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 hig
No
reviews[].products[].thread[].created_atall, productThe UTC date/time the thread entry was created.No
reviews[].products[].thread[].typeall, productThe type of thread entry:
customer_comment – an additional comment made by the customer.
customer_rerate – an adjustment made to the service rating by the customer.
customer_attribute_rerate – an adjustment made to a product attribute rating by the customer.
merchant_comment – an response from the merchant to the customer’s comments
No
reviews[].products[].thread[].authorall, productThe display name of the person who created the thread entry.No
reviews[].products[].thread[].commentall, productThe comment corresponding to the thread entry. This will be absent for customer_rerate.No
reviews[].products[].thread[].old_ratingall, productThe 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_ratingall, productThe 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[].nameall, productThe name of the attribute which has been rerated. Only present for reviews[].products[].thread[].type = customer_attribute_rerate.No
reviews[].products[].thread[].attributes[].old_ratingall, productThe old attribute rating. Only present for reviews[].products[].thread[].type = customer_attribute_rerate (between 1 and 5).No
reviews[].products[].thread[].attributes[].new_ratingall, productThe new attribute rating. Only present for reviews[].products[].thread[].type = customer_attribute_rerate (between 1 and 5).No
reviews[].nps.created_atall, npsThe UTC date/time the NPS feedback was created.Yes
reviews[].nps.ratingall, npsThe 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.reasonall, npsThe reason the customer has provided to accompany their NPS rating. This will only be included where a reason has been provided.