API for Invitations: Walkthrough
Step 1: Finding your API and Secret Key
If your account has API access granted, you can create and manage your API keys by following the quick steps below or via this direct link: https://businessapp.b2b.trustpilot.com/#/applications/
- Log in through business.trustpilot.com
- Select Integrations from the left hand column and click on Developers
- Choose APIs and pick a name for your application to generate your API key and secret
Step 2: Finding your Business-Unit-ID || Video Demo
Your business unit ID is a unique alpha-numeric identifier specific to your domain. It is static and may only change if your domain on Trustpilot changes.
To find the business unit ID, we will be using the Find a business unit endpoint. The required parameter here is the “name” of the business unit, ie. your website’s domain. As a quick example, if you wanted to look up the BUID of Trustpilot, you’d pass along the string “trustpilot.com”.
Try it yourself, just remember to replace the API key.
https://api.trustpilot.com/v1/business-units/find?apikey={{apikey}}&name=trustpilotdemo.com
Once you get the response back you want the “ID” field. This is your BUID for the domain you just
searched.
Step 3: Authentication with OAuth 2.0 || Video Demo
In order to use any private API endpoint on Trustpilot, authentication is required in the form of an access token. Since triggering review invitations is considered a private endpoint, the goal here will be to get an access token first, which you can reuse for multiple API calls while it’s valid. Once expired, you can refresh the token. To jump right into our authentication documentation for more guidance, click here: https://developers.trustpilot.com/authentication
Step 4: Trigger a service review invitation
Once you have your access token, you can use our Create invitation(s) API endpoint. This API call JSON request requires the customer name, email, and some sort of reference ID such as an order ID or invoice number. There are also a number of sender options that you can customize. Here is a sample JSON request:
https://developers.trustpilot.com/invitation-api#create-invitation(s)
{
"consumerEmail": "john.doe@trustpilot.com",
"consumerName": "John Doe",
"referenceNumber": "inv00001",
"replyTo": "john.doe@trustpilot.com",
"locale": "en-US",
"senderEmail": "john.doe@trustpilot.com",
"serviceReviewInvitation": {
"preferredSendTime": "2013-09-07T13:37:00",
"redirectUri": "http://trustpilot.com",
"tags": [
"tag1",
"tag2"
],
"templateId": "507f191e810c19729de860ea"
},
"locationId": "ABC123",
"senderName": "John Doe"
}
NOTE: Leaving out certain sender options such as the “senderEmail”, “templateId”, or
“preferredSendTime” isn’t a problem — this API endpoint will automatically use your default invitation settings enabled in Get Reviews > Invitation Settings within your Trustpilot Business App.
Apart from the sending options mentioned above, you’ll also notice the optional tags and redirectUri fields in that request. Here’s a quick rundown to help you get a better understanding of those:
Tags are extra pieces of specific data that you know about the customer or their purchase. By adding these before the review has been submitted, your reviews will be tagged with hyper-relevant data, allowing for more granular analytics and highly tailored review display. (note: There is no limit to the number of tags you can add. Valid characters are a-z, A-Z, 0-9, underscore, dash, and period. Spaces are not allowed.)
The redirectUri allows you to redirect the customer to any webpage of your choosing once they submit their review. By omitting the redirectUri, reviewers will be brought to a Trustpilot "review submitted" page. If you'd like to bring them back to a custom page on your website — like your own "thank you" page or simply your homepage — you have full control over that (note: Make sure to use a full URL including https, so https://example.com would be valid, wheras example.com would not.).
And that’s all there is to it! Successful API calls will queue up invitations in your Trustpilot Business App, which you can see by logging in to your account and clicking on Get Reviews > Invitation History.
Step 4 [Alternate]: Generate a service review invitation link
Once you have your access token, you can use our Generate service review invitation link API endpoint.This API call JSON request requires the customer name, email, locale, and some sort of reference ID such as an order ID or invoice number. Here is a full sample JSON request:
https://developers.trustpilot.com/invitation-api#generate-service-review-invitation-link
{
"referenceId": "inv00001",
"name": "John Doe",
"tags": [
"tag1",
"tag2"
],
"locale": "en-US",
"email": "john.doe@trustpilot.com",
"redirectUri": "http://trustpilot.com"
}
This API call will return a unique invitation link, which you can send directly over to your customers. We typically see our clients send this over in their own emails to customers, but you can get creative!
3 comments
Sort by Date VotesAL Feratovic Trustpilot
Great Documentation! Very informative.
Naveen K
Thanks very informative document, I just have a question is it possible to have more than one invitation https://developers.trustpilot.com/invitation-api#create-invitation(s).
for ex:- in the payload or post data, I want to send a multiple to the multiple client.
Thanks
Jeremy Robinson Trustpilot
Hi Naveen K --
Great question! The endpoint accepts one customer record, per POST. So, there should be a loop, scheduler or event based process that is sending this over, per customer, per event. ;)
Hope this helps!
Jeremy