Go To Top

How to Build Your Own TrustBox Showing Service Reviews

A guide to building a TrustBox with service reviews using the Trustpilot API.

top_buildyourowntrustbox.jpg

Introduction

This guide will walk you through the different API endpoints you can use to build a TrustBox of your own.

The screenshots in this guide that show API calls are made using the API client application called Postman.

While the API examples provided are valid, they contain “dummy data” and {{placeholder-data}}. Remember to fill in the correct values here.

We recommend that you read the documentation (links) in this document to get a better  understanding of the API calls you’ll be making.

Before you start...

Do you even need this?

We love when people use our APIs to build new things, but remember that we also provide pre-built and easy to set-up TrustBoxes that you can embed on your website without writing any code. This guide is meant for companies that, for one reason or another, can’t use our pre-built TrustBoxes and need to build their own.

What’s a TrustBox?

A TrustBox is a widget you can use to show your reviews, TrustScore, and star ratings on your website or mobile app. You can use it to give visitors a trustworthy impression of your company.

Examples  of some TrustBoxes:

Integration guidelines

Before you start you should read our integration guidelines. The guidelines will tell you how to implement content and display the Trustpilot logo and images correctly.

Authentication

To use the API endpoints described in this guide, you will need an API key.

How to get your TrustScore

To get your current TrustScore, you can use the “Get a business unitendpoint in the Business unit API. This is a simple GET endpoint in the format:
https://api.trustpilot.com/v1/business-units/{{businessUnitId}}
To use the endpoint, you need your business unit id, which you can learn how to
get in the guide How to find your business unit id”.

Here’s the URL for getting the information about Trustpilot:
https://api.trustpilot.com/v1/business-units/46d6a890000064000500e0c3/
Result:

{
 
"links": [ … ],
 
"id": "46d6a890000064000500e0c3",
 
"displayName": "Trustpilot",
 
"name": {
   
"identifying": "www.trustpilot.com",
   
"referring": [
     
"trustpilot.com",
     
"trustpilot.net"
   ]
 },
 
"websiteUrl": "http://trustpilot.com",
 
"trustScore": 6.1,
 
"stars": 3,
 
"country": "US",
 
"numberOfReviews": {
   
"total": 182,
   
"oneStar": 57,
   
"twoStars": 25,
   
"threeStars": 16,
   
"fourStars": 19,
   
"fiveStars": 65
 },
 
"status": "active"
}

Since you likely want to show your star rating, along with a sentence in the format “X.X TrustScore based on X reviews.”, we’re interested in the keys “trustScore”, “stars” and “numberOfReviews.total” from the result.

How to get your latest reviews

To get a list of your latest reviews we need the “Get a business unit’s reviews” endpoint.

For our example, let’s say we want to retrieve a list of all 5 star, english reviews sorted by date (newest first), then it would be in this format:
https://api.trustpilot.com/v1/business-units/{{business-unit-id}}/reviews?stars=5&language=en

here’s the URL for doing just that with the Trustpilot.com business unit:

https://api.trustpilot.com/v1/business-units/46d6a890000064000500e0c3/reviews?stars=5&language=en

Result:

{
 
"links": [ ... ],
 
"reviews": [
   {
     
"links": [ ... ],
     
"id": "999283910000ff00098a9265",
     
"consumer": {
       
"links": [ ... ],
       
"id": "999de5ed000064000127bc3c",
       
"displayName": "Jane Doe",
       
"displayLocation": null,
       
"numberOfReviews": 8
     },
     
"businessUnit": {
       
"links": [ ... ],
       
"id": "9996a890000064000500e0c3",
       
"identifyingName": "www.trustpilot.com",
       
"displayName": "Trustpilot"
     },
     
"stars": 5,
     
"title": "Excellent resource",
     
"text": "Always worth checking Trustpilot before making a purchase. Can't fault the service.",
     
"language": "en",
     
"createdAt": "2016-09-21T12:56:49Z",
     
"updatedAt": null,
     
"companyReply": {
       
"text": "Hi Jane,\n\nThank you for your 5 star review!",
       
"createdAt": "2016-09-21T13:23:11.073Z"
     },
     
"isVerified": true,
     
"numberOfLikes": 0,
     
"status": "active",
     
"reportData": null
   }
 ]
}

As you can see in the result, using the “reviews” key we have a list of reviews. The reviews each have information about the consumer, the business unit, how many stars were given, title of the review, text of the review and a company reply (if available).

How to get reviews based on certain tags

Let’s say you want to get only the reviews you’ve tagged with a tag “ready-for-frontend”, then you simply need to add the parameter “tagValue” to the endpoint above. Here’s an example:
https://api.trustpilot.com/v1/business-units/46d6a890000064000500e0c3/reviews?stars=5&language=en&tagValue=show-in-trustbox