Welcome to our quick start guide on how to efficiently add tags to reviews that contain particular strings using Trustpilot's API. This process allows you to categorise reviews for better organisation and insights according to segments of your business. In this article, we’ll show you how to retroactively add and manage tags for your service reviews based on the reviews you receive.

To pre tag your reviews using the API see this documentation for how to add tags to your invitations using the Create Invitation(s) API, create service review link, create product review link.

Prerequisites

To use the Set tags API endpoint, you'll need the following:

Trustpilot business account - create one here

Trustpilot Connect add-on Module/ Enterprise plan - get the module here or reach out to your Customer Success Manager to upgrade your plan

API client - optional (we would recommend Postman)

Generating an Access Token

To access Trustpilot's Private APIs, the first step is to generate an access token. I'll walk you through the process in this blog. Once you have your token, you can use it to interact with Trustpilot's API.

Accessing Service Reviews

After obtaining your access token, the next step is to pull down all service reviews for a specific business unit. For example, the endpoint to retrieve reviews for a business unit is:

GET https://api.trustpilot.com/v1/private/business-units/{{business_unit_id}}/reviews

The business unit id is a unique string assigned to a domain on Trustpilot. To find your business unit id using your API key and the Find a business unit API, you will be able to enter a string with your company’s domain i.e (trustpilotdemo.com) under the param “name” and it will return a response with an id string. This is your unique alpha-numeric identifier specific to your domain as assigned by Trustpilot. Video demo

Filtering Reviews for Specific Strings

Using the received reviews from the API, filter the reviews.text field to identify those containing the particular string you are interested in. Extract the corresponding reviews.id from these reviews.

Retroactively Adding Tags to Reviews

With the identified review IDs, you can now make individual calls to each review's endpoint to attach tags retroactively. The endpoint for adding tags to a review is:

POST https://api.trustpilot.com/v1/private/reviews/{{review_id}}/tags

The request body should contain JSON formatted data to add tags, such as:

"tags": [
          {
            "group": "generic",
            "value": "Blinds"
           }
        ]

Note: You can't use special characters or spaces in tag names (:<>/%#&?',♫♪☁★).

Your tags are only displayed in the private API, and they are not visible on your company’s profile page on Trustpilot. However, tags are still considered public data because it’s possible to filter reviews by tag through our public API (if someone knows what to filter for).

Write tags in a way that only internal employees understand. Use internal coding systems to encrypt tags, such as a “mobileunitA” rather than “iPhone” or “mobileunitB” rather than “Samsung Galaxy”.

Additional Assistance

Feel free to reach out if you require further guidance or support during this process. We're here to help you effectively leverage Trustpilot's APIs to manage and enhance your review system.

Let me know if you have any questions or need additional assistance. Good luck with adding tags to your Trustpilot reviews!

Node.js Example

Node.js Example which I have written for a fake company called “Curtainz4u”

const response = {
    "links": [
        {
            "href": "https://api.trustpilot.com/v1/private/business-units/556727b40000ff345678765434demo/reviews",
            "method": "GET",
            "rel": "next-page"
        },
        {
            "href": "https://api.trustpilot.com/v1/business-units/556727b40000ff345678765434demo",
            "method": "GET",
            "rel": "business-units"
        }
    ],
    "reviews": [
        {
            "links": [
                {
                    "href": "https://api.trustpilot.com/v1/reviews/654a19a8290e11dc4428demo",
                    "method": "GET",
                    "rel": "reviews"
                },
                {
                    "href": "https://api.trustpilot.com/v1/reviews/654a19a8290e11dc4428demo/web-links",
                    "method": "GET",
                    "rel": "reviews-web-links"
                },
                {
                    "href": "https://api.trustpilot.com/v1/resources/images/stars/3",
                    "method": "GET",
                    "rel": "resources-images-stars"
                }
            ],
            "id": "654a19a8290e11dc4428demo",
            "consumer": {
                "links": [
                    {
                        "href": "https://api.trustpilot.com/v1/consumers/624bf076f503fd00124demo",
                        "method": "GET",
                        "rel": "consumers"
                    }
                ],
                "id": "624bf076f503fd00124demo",
                "displayName": "Jane Doe",
                "displayLocation": null,
                "numberOfReviews": 2
            },
            "businessUnit": {
                "links": [
                    {
                        "href": "https://api.trustpilot.com/v1/business-units/556727b40000ff345678765434demo",
                        "method": "GET",
                        "rel": "business-units"
                    }
                ],
                "id": "556727b40000ff345678765434demo",
                "identifyingName": "www.curtainz4u.com",
                "displayName": "Curtainz4u"
            },
            "stars": 3,
            "title": "Immaculate Service",
            "text": "Great customer service",
            "language": "en",
            "location": null,
            "createdAt": "2023-11-07T13:04:08Z",
            "updatedAt": null,
            "experiencedAt": "2023-10-04T00:00:00Z",
            "referralEmail": null,
            "referenceId": "121415",
            "source": "Organic",
            "companyReply": null,
            "tags": [],
            "numberOfLikes": 0,
            "findReviewer": {
                "isEligible": true,
                "requests": []
            },
            "isVerified": false,
            "status": "active",
            "reportData": null,
            "countsTowardsTrustScore": true,
            "countsTowardsLocationTrustScore": null,
            "invitation": null,
            "businessUnitHistory": [],
            "reviewVerificationLevel": "not-verified"
        }
    ]
}
// Extracting reviews from the response
  const reviews = response.reviews;
 
 // Filtering reviews based on the text containing "service"
  const reviewsWithServiceString = reviews.filter(review => review.text.toLowerCase().includes("service"));
 
 // Extracting the IDs of the filtered reviews
  const idsOfReviewsWithServiceString = reviewsWithServiceString.map(review => review.id);

  // Output the IDs of reviews containing "service"
  console.log(idsOfReviewsWithServiceString);

  // Function to add tags to individual reviews
  async function addTagsToReviews(reviewId) {
    try {
      const response = await fetch(`https://api.trustpilot.com/v1/private/reviews/${reviewId}/tags`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          // Add your Trustpilot access token in the Authorization header
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN_HERE'
        },
        body: JSON.stringify({
          "tags": [
            {
              "group": "generic",
              "value": "Blinds"
            }
          ]
        })
      });
      if (response.ok) {
        console.log(`Tags added successfully to review ID: ${reviewId}`);
      } else {
        console.error(`Failed to add tags to review ID: ${reviewId}`);
      }
    } catch (error) {
      console.error('Error:', error);
    }
  }
  // Loop through each review ID and add tags
  async function processReviews() {
    try {
      for (const reviewId of idsOfReviewsWithServiceString) {
        await addTagsToReviews(reviewId);
        // Assuming a small delay between API calls to avoid rate limit issues
        await new Promise(resolve => setTimeout(resolve, 1000)); // 1-second delay
      }
    } catch (error) {
      console.error('Error processing reviews:', error);
    }
  }
  // Execute the process
  processReviews();

 

Additional resources

Tag your Service Reviews Support Article