For Integration Builders

Introduction

Welcome to the documentation for integrations built by Trustpilot partners, which enable business users to collect, showcase, manage, and learn from reviews with our partners’ solutions. This section includes the technical details you’ll need to create and implement a partner integration, as well as the details of our Integration Partner Program, including the application process, the requirements to be accepted and guidance on how to become a top-tier integration partner. Check our integration directory for inspiration from other partners.

Building an Integration

To begin building and implementing an integration, you’ll first need to be approved to create a Trustpilot partner integration by applying here (learn more about this step in the next section on our Integration Partner Program). Then, you’ll receive your Partner API Keys, and can follow the below instructions to start building.

1. Get your partner credentials from Trustpilot

Once approved after submitting your application, your Partner Manager will:

• Send over your Partner API keys and your Partner ID
• Ask you for an email address that you’d like to use as your Trustpilot business user login. You’ll need this Trustpilot business user in order to complete Step 2 below.
• Ask you to provide any Redirect URIs so that we can allowlist them for your OAuth2.0 workflow in Step 6. For whitelisting, you can simply provide us a base domain or subdomain — it doesn’t need to be the full path URI.

2. Generate an access token using your partner credentials

To generate a partner access token, you can follow the Grant Type: Password steps in our documentation here: Authentication - Trustpilot API Documentation

This will allow you to create an access token for Steps 4-5. The access token lasts for 100 hours, and after that time is up, you can simply generate a new one or refresh your token as outlined in the documentation above.

Below is an example of generating an access token with Grant Type: Password using Postman:

3. Prompt customer for their domain to get their Business Unit ID (BUID)

Now that you have your partner access token, you can prompt the customer for their domain to check that they’re eligible to use partner-built integrations (Step 4) and to generate API keys for that customer (Step 5). Once you have their domain, use our Find a business unit API endpoint to get their BUID.

The required parameter here is the “name”, ie. the website’s domain. As a quick example, if you wanted to look up the BUID of Trustpilot’s demo site trustpilotdemo.com, you’d pass along the string “trustpilotdemo.com”.

Try it yourself, just remember to replace the API key with your own partner API key.

https://api.trustpilot.com/v1/business-units/find?apikey={{apikey}}&name=trustpilotdemo.com

Example response:

Once you get the response back you want the “id” field. This is the BUID for the domain you just searched.

4. Check the BUID’s permissions and eligibility

Customers need to have partner permissions enabled in their Trustpilot Business app. Prompt the customer to toggle this on, if it’s disabled here: https://businessapp.b2b.trustpilot.com/account/permissions 

Using your partner ID (Step 1), your partner access token (Step 2), and the customer’s BUID (Step 3), you can now check if this customer is eligible to use partner-built integrations:

HTTP Method: GET
URL: https://api.trustpilot.com/v1/private/partners/{partnerId}/check/{businessUnitId}

Parameters:

Responses

5. Create API keys for the customer

If you have received a greenlight in the form of a 201 status code in Step 4 and the customer has enabled partner permissions in their Trustpilot account, you can now generate API keys on behalf of the customer.

HTTP Method: POST
URL: https://api.trustpilot.com/v1/private/partners/{partnerId}/key/{businessUnitId}

Parameters:

Responses

6. Prompt customer to go through OAuth2.0

To generate a customer access token, you use the customer API keys generated in Step 5 and follow the Grant Type: Authorization Code steps in our documentation here: https://developers.trustpilot.com/authentication#auth-code

Using these steps, you’ll present companies with a Trustpilot login form based on the documentation above. Once they login, it will redirect to a URI of your choosing with the authorization code appended on — just make sure that you’ve provided us with this Redirect URI ahead of time (Step 1)!

Once you have the Authorization Code, you can generate the customer access token and store that on your side. This will allow you to make /private/ API calls on behalf of the customer — these calls will be labeled with Authentication: Business user OAuth Token in our documentation.

Keep in mind that the access token lasts for 100 hours, and after that time is up, you can refresh the token using the same guide above.

7. Accepted Integration Use Cases

The below use cases for integrations are the most popular and deliver the most value to our users. We generally will accept any integration with one of these use cases into our Integration Partner Program. If you have ideas for an integration that meets a use case not listed here, please let us know! We’re always open to new ideas if they deliver real value to our mutual customers.

We’ve linked to documentation about the most commonly used endpoints below, but please explore the rest of this developer site for more.

Invite

Use the API to trigger a review invitation from a business to their customer in response to a certain event. This use case is common for ESPs and eCommerce platforms.

• Create invitation(s): This API endpoint triggers email invitation(s) to send from Trustpilot’s system. You can create both service review invitations and product review invitations using this endpoint. If you only want to create a service review invitation, you can omit the productReviewInvitation section.

• Generate service review invitation link: Generate a unique invitation link that can be sent to a consumer by email or website. Use the request parameter called redirectURI to take the user to a product review link after the user has left a service review.

• Create a product review invitation link: Given information about the consumer and the product(s) purchased, get a link that can be sent to the consumer to request reviews. Can be used alone or as a redirectURI for the link service review invitation link above

Showcase

Use the API to showcase real-time reviews and ratings on different platforms and channels. This use case is common for ESPs, personalization and conversion tools, and image/video generators.

• Get a business unit’s reviews: This method gets all the reviews written about the business unit and does not include private information.

• Get product reviews: This method allows you to get business unit product reviews for SKUs and / or productUrls.

Reply

Use the API to manage and reply to reviews from a third-party platform. This use case is common for helpdesks, reputation managers, and social aggregators.

• Reply to a review: By using the reviewId from the "Business unit private reviews" endpoint above, you can respond directly to reviews.

• Reply to a product review: Create a new comment for a product review.

Review Ingestion for Analysis

Use the API to ingest the reviews for use in analysis. This use case is common for reputation management and analytics services.

• Business unit private reviews:Once you have an access token for a specific business user, you'll be able to use that token on any private API call for any of the domains on their account.

With location reviews:

Get all Locations

https://api.trustpilot.com/v1/business-units/{{businessUnitId}}/locations?apikey={{apikey}}

Quick notes:

• Our Locations offering is relatively new, so not all businesses choose to set up locations on Trustpilot and will just collect on the brand level.

• If the business has locations, the API endpoint will list up to 200 locations. To paginate, you can use the 'page' parameter (eg. ?page=2, ?page=3, etc).

• If the business unit doesn't have any locations, the response will return an empty array.

Integration Partner Program Details

Overview

Trustpilot’s Integration Partner Program rewards partners who build great integrations with marketing, technical, and partnership support. Partners accepted into the program will be featured on our Integrations Directory. By driving adoption of their integrations, partners will unlock higher tiers of support.

To be accepted to the entry level of the Integration Partner Program, integrations must meet a series of requirements.

Requirements

1. The integration is built following the instructions in this article, including the use of oAuth authentication.
2. The integration meets at least one of the accepted integration use cases.
3. The integration has been tested by 5 beta users.
4. Provide a test account with full access for Trustpilot’s product team.
5. Provide support for end-users: publish thorough support documentation and provide contact information for customers who need integration support.
6. Agree to our terms and sign our Master Partner Agreement.

Who can use the integration?

In general, partner-built integrations are available to users on a paid Trustpilot plan. Free users will not have access to the integration.

How to apply

1. Fill out our application form to tell us about the integration and to request API credentials.
2. Your request will be approved based on your proposed use case. Our accepted integration use cases are generally always approved, but we’ll review other ideas on a case by case basis.
3. If approved, your Partner Manager will share our Master Partner Agreement for signature.
4. Once signed, your Solutions Engineer will supply your API credentials and will be available for questions and technical guidance.
5. After completing your integration and meeting all requirements listed, demo the integration for your Solutions Engineer for final technical approval.

Becoming a top-tier integration partner

Any partner who meets all requirements listed in this article can be accepted to our Integration Partner Program as an entry-level partner, which will allow your integration to be listed in our public directory. To become a mid-or top-tier partner, we have only one criteria: integration adoption. As more customers become active users of the integration, you’ll unlock new tiers of co-marketing, go-to-marketing, enablement, and commercial support. We have a few best practices that our top-tier integration partners are already following to increase adoption.

Account mapping

Almost all of our integrations are available to users on our paid Standard plan. We suggest that all new partners begin by mapping accounts with us so that we can identify joint customers who already have access to the integration. We highly recommend using either Crossbeam or Reveal to do so in a secure and easy way. If you do not use either of these services, we can also do a manual account-mapping exercise.

Targeted communication

After completing this exercise, you’ll have a list of all customers who have access to this integration. Use it to segment communication to them and encourage adoption in a targeted way.

1. Train your customer-facing representatives on the new integration so that they can share it with customers when relevant.
2. Announce the integration to current joint customers across channels. At a minimum, we recommend email, in-app messaging, and CSM outreach.
3. Add the integration to the user journey so future customers can find it. We recommend including it in CSM onboarding calls, in automated onboarding emails, and in your user dashboard.

Though social media posts, newsletters, and press releases can drive awareness and adoption (and we definitely encourage these as well!), we’ve seen that the above steps will have the biggest impact on adoption.