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



If you would like to manage your own display solution, Feefo's Review API allows you to retrieve all the data you need. However, this solution 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 yur requirements into consideration.



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

Response parameter

Modes

 Description

Authent-ication required

Response parameter

Modes

 Description

Authent-ication required

reviews[].tags[].type

all, service, product, nps

The type of tag associated with the feedback:

sale – provided as part of the sale upload.

feedback – applied via Insight Tags.

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

Response parameter

Modes

 Description

Authent-ication required

reviews[].customer.mobile

all, service, product, nps

The mobile phone number of the customer as provided in the original sale upload

Yes

Response parameter

Modes

 Description

Authent-ication required

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:

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[].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:

product – provided as part of the sale upload, corresponds to the specific order line.

feedback – applied via Insight Tags.

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:

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_url

all, product

The 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_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:

photo

video 

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:

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[].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.