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 integrations, you need to be part of the Trusted Integration Program. For further information, refer to Become an Integration Partner.

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 Client credentials 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 has until expiration, 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. To turn off MFA, refer to Set up and manage 2 step verification.

Step three: Get the customer’s Business Unit ID

To allow a customer to use your integration, you need to get your customer’s Business Unit ID (domain). You’ll need your customer’s Business Unit ID to check that they’re eligible to use your integration and generate API Keys for them.

To get a customer’s Business Unit ID, use the following steps: Prompt your customer for their Trustpilot domain. A Trustpilot domain is the website associated with a Trustpilot profile, for example: Trustpilot.com. Call the Find a Business Unit API endpoint. To find a Business Unit, you need to provide your API key in the header and use the following example:

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

Find the Business Unit ID in the response. Refer to the following 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: Prompt your customer to turn on Partnership Permissions in the Trustpilot Business app > Settings > Partnership Permissions. Customers must have an Admin for their Trustpilot account to update their permissions. Use the following API call to 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>"

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 you’ve checked that the customer has the correct permissions and you’ve received a 201 response, you can generate an API Key on behalf of the customer.

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.