Build a partner integration

Partner integrations are publicly available integrations that any Trustpilot Business customer can find in the Integrations directory. To build a partner integration, you need to be part of the Trusted Integration Program. For further information, refer to Become an Integration Partner.

If your integration stores consumer or review information, you must adhere to consumer requests to delete their data. For further information, refer to the Deletions API.

If you’re already an Integration Partner, use the following steps to build a partner integration.

Step one: Get your partner credentials

As an Integration Partner, you have access to a Partner Manager who provides you with your Partner credentials. Your Partner Manager should provide you with the following:

• Your Partner API Keys and Partner ID.
• Your Business User login. You’ll need to provide an email address to use.

During step one, you also need to provide your Partner Manager with any redirect URLs to add to the OAuth2.0 allowlist. In step six, you’ll need to prompt your customer through authentication that requires redirect URLs.

Step two: Generate a Partner access token

Access tokens allow you to call Trustpilot’s private APIs. To generate your Partner access token refer to the Password grant type documentation and complete the steps provided. Access tokens expire after 100 hours and refresh tokens expire after 30 days. When your current access token expires, you can use your refresh token to request a new access token. To check how long your access token has left, use expires_in.

Note

If you use the Authorization code or Implicit grant type, you must tell your users to turn off multi-factor authentication when they log in. OAuth authentication doesn’t support multi-factor authentication.

Step three: Get the customer’s Business Unit ID

To enable a customer to use your integration, you’ll need to check that they’re eligible and generate API keys for them. To do this, you need their Business Unit ID.

To get a customer’s Business Unit ID, use the following steps:

1. Ask your customer for their Trustpilot domain. A Trustpilot domain is the website associated with a Trustpilot profile, for example: Trustpilot.com.
2. Add your API key and your customer’s Trustpilot domain to the following example:

curl -X GET "https://api.trustpilot.com/v1/business-units/find" \
 -G \
-H "apikey: <your api key>"
\
--data-urlencode "name=<Your customer’s domain>"

3. Get the Business Unit ID from the response:

"id": "507f191e810c19729de860ea", <-- This is the Business Unit ID
  "displayName": "Trustpilot",
  "name": {
    "identifying": "trustpilot.com",
    "referring": [
      "trustpilot.com",
      "www.trustpilot.com"]

Step four: Check the customer’s permissions

Trustpilot Business customers need to have the connect module to use partner-built integrations. To check that your customer is eligible to use your integration, use the following steps:

1. Prompt your customer to turn on Partnership Permissions in Trustpilot for Business > Settings > Partnership Permissions. Only a customer’s admin user can update permissions.
2. Use the following API call to check that your customer is eligible:

curl -X GET " https://api.trustpilot.com/v1/private/partners/<Your partner ID>/check/<Your customer's businessUnitId>"

3. Check the responses. The following table shows the possible responses and what they mean:

Response code	Description
200	Customer does not have rights to use this integration
201	Customer has sufficient right to use partner integration
403	Incorrect authentication for Business Unit

Step five: Generate an API Key for the customer

If your customer has the correct permissions, you can generate an API Key on their behalf. To generate an API Key for a customer, use the following example:

curl -X POST "https://api.trustpilot.com/v1/private/partners/<Your Partner ID>/key/<Your customer's Business Unit ID>"

The following table shows the possible responses and what they mean:

Response code	Description
200	Customer does not have permissions to use this integration
201	PartnerCustomerKey has been created
403	Incorrect authentication for Business Unit
404	Incorrect PartnerID

Step six: Prompt the customer through authentication

In order to call private APIs on behalf of the customer, they need to sign in through an OAuth2.0 flow. To set up OAuth2.0 for your customer, use the Authorization code grant type. The Authorization Code grant type generates and submits an authorization code to get an access token. You’ll need to add your partnerID to the HTTP header to get an access token on behalf of your customer. Access tokens last for 100 hours. Once your access token expires, your customer needs to login in to get a new authorization code.

Note

Make sure you provide your Partner Manager with a list of redirect URLs in Step One: Get your partner credentials.