Switch Reviews Provider

TABLE OF CONTENTS

• Introduction
• Initial considerations
• Proceeding with import
• Integrating Your Imported Reviews in to Feefo
• Request Parameters (Both Endpoints)
• Additional Request Parameters (/api/version/importedreviews/[service/product])
• Additional considerations
• Summary

---

 

Introduction

This document provide support guidance for merchants wishing to import their reviews from a previous provider to the Feefo platform. Their are two main stages to this process:

• Importing reviews
• Integration of reviews

---

 

Initial considerations

As you embark on your journey with Feefo, we'd like to ensure a smooth transition when importing your reviews. There are a few essential steps to consider before you start this process:

1. Review Your Previous Provider's Contract:

   Carefully examine your contract with your previous feedback platform. Not all platforms allow the transfer of your reviews when you switch providers, so it is crucial to understand any limitations or restrictions in your existing agreement.
   Before importing your existing reviews into the Feefo platform, we recommend transferring the data via SFTP. It will then undergo our rigorous ingestion program to ensure compliance. If required, this will involve us contacting your customers on your behalf, requesting their permission to display their reviews on the Feefo platform. Note, all email records are then securely deleted in accordance with GDPR guidelines.

2. Ensure Data Integrity:

   We value the authenticity of reviews. Make sure that any data you share with us is genuine and has not been manipulated in any way. It should not be selectively provided to skew your service or product scores. Authenticity is at the core of our review ecosystem.

3. Feefo Terms and Conditions:

   Please be aware that when using Feefo's services, our standard terms and conditions apply. Additionally, our content standards must be adhered to. These guidelines ensure that our review ecosystem maintains its integrity and fairness.

---

 

Proceeding with import

To import reviews in to your Feefo account our Technical Support department will require a file containing your historical reviews. The structure of the file differs depending on whether service or product related reviews are being imported into Feefo. In both cases the file will need to be provided in a CSV (comma separated value) format.

Service Review Format

Column heading	Description	Required
email	Only required if Feefo are required to solicit permission from the consumer to display the review. Please contact Feefo support to arrange a secure method of transferring data that includes email addresses.	Optional
date	The date the feedback was received in UTC format	Required
type	Defaulted to SERVICE	Required
rating	The star rating assigned to the feedback (1 – 5)	Required
source	The name of the platform where the review was captured	Required
vendor_ref	The product SKU the transaction related to	Required
review_title	The title of the review	Required
reviewer_display_name	Display name of the person leaving the review. Can be Full Name or Initials	Required
comment	The service review content	Required

 

Example service file  - No import permission required

Example service file  - Import permission required

 

Product Review Format

Column heading	Description	Requirement
email	Only required if Feefo are required to solicit permission from the consumer to display the review. Please contact Feefo support to arrange a secure method of transferring data that includes email addresses.	Optional
date	The date the feedback was received in UTC format	Required
type	Defaulted to PRODUCT	Required
rating	The star rating assigned to the feedback (1 – 5)	Required
source	The name of the platform where the review was captured	Required
vendor_ref	The product SKU the transaction related to	Required
parent_vendor_ref	The parent product SKU the transaction related to	Required
reviewer_display_name	Display name of the person leaving the review. Can be Full Name or Initials	Required
comment	The service review content	Required
product_rating_name	(Optional, multiple columns) If you hold attribute ratings for your products these can be imported by substituting “name” in the column heading with the attribute name and providing the rating assigned to the attribute (1-5)	Required
Additional attributes	Any number of additional columns with more information pertaining to the review can be added to the file which will be stored as additional attributes against the review e.g. “Colour”	Required

 

Example product file - No import permission required

 

Example product file - Import permission required

email	date	type	rating	source	vendor _ref	reviewer _display _name	comment	product _rating _fit	product _rating _style	Colour
mark.thomas @email.com	5/04/2015	PRODUCT	3	Trust Advisor	SKU 123	Mark Thomas	It is OK, a bit smaller than expected.	1	4	Red
s.wright @email.com	5/04/2015	PRODUCT	5	Trust Advisor	SKU 456	S Wright	Really pleased with this!	5	4	Green

 

Once our technical department have been given access to this file, subject to validation, it will be imported in to your Feefo account and your imported reviews will be available for integration.

 

Integrating Your Imported Reviews in to Feefo

Feefo provides a dedicated API which provides all the data you need to build your website reviews integration. The API returns your review summary/detail data in a JSON format which can be easily consumed by your website for the purposes of integration.

API Endpoint: https://api.feefo.com/api/version/importedreviews/summary/[service/product]

Used to retrieve summary information such as total counts and average scores spanning both your Feefo & imported reviews.

• /api/version/importedreviews/summary/service (mode = service) – the review summary for a specified merchant
• /api/version/importedreviews/summary/product (mode = product) – the product review summary for a specified merchant. Requires a product_sku or parent_product_sku to beprovided

API Endpoint: https://api.feefo.com/api/version/importedreviews/[service/product] 

Used to retrieve a detailed listing of Feefo + imported reviews.

• /api/version/importedreviews/service (mode = service) – the service reviews for a specified merchant
• /api/version/importedreviews/product (mode = product) – the product reviews for a specified merchant. Requires a product_sku or parent_product_sku to be provided

Request Parameters (Both Endpoints)

Request Method: GET

Request Parameter	Values/Default	Required/Optional	Description
merchant_identifier	String	R	Unique identifier for the merchant account.
date_time	String	O	Filter reviews to those created on a specified UTC date / time (time part optional, defaulted to 00:00:00 when not supplied). Accepted query language: = | < | <= | > | >=. When = is used the time part will be excluded from the query. Overrides: since_period.
product_sku	string	O	Filter for product reviews assigned to the specified product search code.
			Multiple product SKUs can be provided in one request separated by commas.
			●      A wildcard character (*) is supported at the beginning and/or end of the supplied parameter to support partial matching for related/variant products.
parent_product_sku			Filter for product reviews assigned to the specified parent product search code. A parent product search code can span multiple product search codes / variants. Case insensitive. Overrides: product_sku.
rating	string	O	Filters feedbacks returned to specified ratings. The request can include multiple comma separating ratings (1-5).
			mode = service – the feedback will be suppressed if it is a  service review and it does not match the specified filter
			mode = product – the feedback will be suppressed if is it a  product review and the rating does not match the specified  filter
feefo_reviews	true/false	O	false – Imported review review
			true – Feefo verified review
			Filters feedbacks based on whether they are collected via Feefo or imported into the database from a 3rd party.
imported_date_time	string	O	Filter reviews to those imported on a specified UTC date / time (time part optional, defaulted to 00:00:00 when not supplied).
			Accepted query language: = | < | <= | > | >=. When = is used the time part will be excluded from the query.

Additional Request Parameters (/api/version/importedreviews/[service/product])

Request Method: GET

Response Parameter	Default	Mode	Auth	O	Description
summary.meta.count					The total number of matching sales corresponding  to the feedback result set.
summary.meta.pages					The number of pages of results available.
summary.meta.page_size					The number of results per page.
summary.meta.current_page					The current page of results being returned.
reviews[].last_updated_date					The UTC date/time the customer’s review was last updated. For imported reviews this will be the creation date.
reviews[].products_purchased[]				Y	The title of all products associated with the sale (including those which have not received feedback). For imported reviews they will only ever be one product.
reviews[].imported					false – Feefo review
					true – Imported review
reviews[].imported_source					Omitted for Feefo reviews.
reviews[].imported_custom					Omitted for Feefo reviews, custom imported review properties returned as a JSON document.
reviews[].tags[].key			Y	Y	The key of the sale tag associated with the feedback.
reviews[].tags[].values[]			Y	Y	The value of the sale tag associated with the feedback, there may be multiple values corresponding to the specified key.
reviews[].tags[].type			Y	Y	The type of tag associated with the feedback.
	sale				sale – provided as part of the sale upload
	feedback				feedback – applied via Insight Tags
reviews[].url		S		Y	The URL of the review on Feefo’s site.
		P
reviews[].social.facebook		S		Y	The URL of the Facebook share link for the review
		P
reviews[].social.google_plus		S		Y	The URL of the G+ share link for the review
		P
reviews[].social.twitter		S P		Y	The URL of the Twitter share link for the review
reviews[].customer.display_name		S P		Y	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.
reviews[].customer.display_location		S P		Y	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.
reviews[].customer.name			Y	Y	The name of the customer as provided in the original sale upload
reviews[].customer.email			Y	Y	The email address of the customer as provided in the original sale upload
reviews[].customer.order_ref			Y	Y	The order reference associated with the feedback
reviews[].customer.customer_ref			Y	Y	The customer reference associated with the feedback. This will only be included where there is an associated customer reference.
reviews[].service.rating.min	default: 1	S			The lowest possible rating
reviews[].service.rating.max	default: 5	S			The highest possible rating
reviews[].service.rating.rating	01-May	S			The service rating assigned to the feedback. For Feefo reviews, where the customer has re-rated their feedback the most recent rating assigned will be returned.
reviews[].service.id		S			The unique id for the service review element
reviews[].service.created_at		S			The UTC date/time the service feedback was created.
reviews[].service.title		S		Y	The title assigned to the service feedback. Where the customer has chosen not to provide a title this will be omitted.
reviews[].service.review		S			The customer’s original review of the merchant’s service.
reviews[].service.helpful_votes		S		Y	The number of helpful votes the service feedback has received.
reviews[].service.custom[].question_id		S	Y	Y	The unique ID of the custom service question.
reviews[].service.custom[].question		S	Y	Y	The title of the custom service question. This is only included if the customer provided a response to the question.
reviews[].service.custom[].answer		S	Y	Y	The response to the custom service question. This is only included
					if the customer provided a response to the question.
reviews[].service.thread[].created_at		S		Y	The UTC date/time the thread entry was created.
reviews[].service.thread[].type		S		Y	The type of thread entry:
	customer_ comment				customer_comment – an additional comment made by the customer
	customer_ rerate				customer_rerate – an adjustment made to the service rating by the consumer
	customer_ retitle				customer_retitle – an adjustment made to the service review title by the consumer
	merchant_ comment				merchant_comment – a response from the merchant to the customer’s comments
reviews[].service.thread[].author		S		Y	The display name of the person who created the thread entry.
reviews[].service.thread[].comment		S		Y	The comment corresponding to the thread entry. This will be absent for customer_rerate | customer_retitle.
reviews[].service.thread[].old_rating	01 May	S		Y	The previous service rating assigned by the consumer. Only present for customer_rerate.
reviews[].service.thread[].new_rating	01 May	S		Y	The new service rating assigned by the consumer. Only present for customer_rerate.
reviews[].service.thread[].new_rating		S		Y	The old review title. Only present for customer_retitle.
reviews[].service.thread[].new_title		S		Y	The new review title. Only present for customer_retitle.
summary.product.parent_ sku		P			Parent product search code the reviews relates to. A parent product search code can span multiple product search codes / variants. If this value is not set against the product it will not be returned.
reviews[].products[].product.sku		P			The SKU assigned to the product.
reviews[].products[].product.tags[] .key		P	Y	Y	The key of the product tag associated with the product feedback.
reviews[].products[].product.tags[] .values[]		P	Y	Y	The value of the product tag associated with the product feedback. There may be multiple values associated with the specified key.
reviews[].products[].product.tags[] .type		P	Y	Y	The type of tag associated with the feedback.
	product				●   product – provided as part of the sale upload, corresponds to the specific order line
	feedback				●   feedback – applied via Insight Tags
reviews[].products[].rating.min	default: 1	P			The lowest possible rating.
reviews[].products[].rating.max	default: 5	P			The highest possible rating.
reviews[].products[].rating.rating	01 May	P			The product rating assigned to the feedback. For Feefo reviews where the customer has re-rated their feedback the most recent rating assigned will be returned.
reviews[].products[].attributes[] .name		P			The name of the product attribute which has been rated.
reviews[].products[].attributes[] .min	default: 1	P			The minimum rating which could have been assigned to the attribute.
reviews[].products[].attributes[] .max	default: 5	P			The maximum rating which could have been assigned to the attribute.
reviews[].products[].attributes[] .rating		P			The rating which has been assigned to the attribute.
reviews[].products[].id		P			The feedback id for the product review element
reviews[].products[].created_at		P			The UTC date/time the product feedback was created.
reviews[].products[].review		P			The customer’s original review of the product.
reviews[].products[].helpful _votes		P			The number of helpful votes the product feedback has received
reviews[].products[].media[] .id		P		Y	The Object ID of the media item
reviews[].products[].media[] .type		P		Y	The type of media attached to the product feedback
reviews[].products[].media[] .url		P		Y	The URL to the media item
reviews[].products[].media[] .thumbnail		P		Y	The URL to the video static thumbnail. Only present for type = video.
reviews[].products[].media[] .caption		P		Y	The consumer provided caption for the media item
reviews[].products[].media[] .helpful_votes		P		Y	The number of helpful votes the product media item has received.
reviews[].products[].custom[] .question_id		P	Y	Y	The unique ID of the custom product question.
reviews[].products[].custom[] .question		P	Y	Y	The title of the custom product question. This is only included if the customer provided a response to the question.
reviews[].products[].custom[] .answer		P	Y	Y	The response to the custom product question. This is only included if the customer provided a response to the question.
reviews[].products[].thread[] .created_at		P		Y	The UTC date/time the thread entry was created.
reviews[].products[].thread[] .type		P		Y	The type of thread entry:
	customer_ comment				customer_comment – an additional comment made by the customer
	customer_ rerate				customer_rerate – an adjustment made to the product rating by the consumer
	customer_ attribute_ rerate				customer_attribute_rerate – an adjustment made to a product attribute rating by the consumer
	merchant_ comment				merchant_comment – a response from the merchant to the customer’s comments
reviews[].products[].thread[] .author		P		Y	The display name of the person who created the thread entry.
reviews[].products[].thread[] .comment		P		Y	The comment corresponding to the thread entry. This will be absent for customer_rerate | customer_attribute_rerate.
reviews[].products[].thread[] .old_rating	01 May	P		Y	The previous service rating assigned by the consumer. Only present for customer_rerate.
reviews[].products[].thread[] .new_rating	01 May	P		Y	The new service rating assigned by the consumer. Only present for customer_rerate.
reviews[].products[].thread[] .attributes[].name		P		Y	The name of the attribute which has been rerated. Only present for customer_attribute_rerate.
reviews[].products[].thread[] .attributes[].old_rating	01 May	P		Y	The old attribute rating. Only present for customer_attribute_rerate.
reviews[].products[].thread[] .attributes[].new_rating	01 May	P		Y	The new attribute rating. Only present for customer_attribute_rerate.

O = Omitted for Imported Review?

P = Product

S = Service

You can display imported reviews using our selection of customisable widgets, all except the Service Review Carousel which exclusively features reviews collected by Feefo. This integration provides you with flexibility and control over how your reviews are showcased to your audience.

---

 

Additional considerations

While importing reviews can be a valuable part of your transition to Feefo, there are some important points to keep in mind:

1. Feefo Hub and Merchant Page:
   Imported reviews will not be displayed in the Feefo Hub or on your Feefo merchant page. These platforms exclusively showcase reviews collected by Feefo.
   
   
2. Google Seller Ratings and Product Ratings Feeds:
   We are unable to include imported reviews in Seller Ratings or Product Ratings feeds to Google. Your previous provider may have already uploaded them to Google, making it challenging for us to vouch for their validity.
   
   
3. Feefo Verified Badge:
   On your website, reviews collected by Feefo will bear a 'Feefo verified' badge next to them for added credibility. Imported reviews, however, will not carry this badge.
   
   
4. Use of APIs:
   If you're utilising our APIs, imported reviews will only be accessible via the 'importedreviews' API. Please feel free to reach out to our support team for additional details if required.
   
   
5. Topic/Sentiment Analysis:
   It's important to note that imported reviews cannot be processed for topic or sentiment analysis within the Feefo system.

---

 

Summary

We're here to support you every step of the way in your journey with Feefo. If you have any questions or require further assistance, our dedicated support team is always ready to help.