How to request a customer review

Pro and advanced plans have the possibility to request a certain amount of reviews per month, to their customers.

This will generate a link, that once accessed, will prompt the user to write a review to your profile.

If the user doesn’t have an account, it’ll be automatically created with the email and name provided in the request.

This can only be done via API, as it’s intended for automations. For instance, when a customer has completed a purchase on your site, you can send them a link requesting them to write a review to your profile on Trusted Humans.

This functionality is extremely helpful to increase your reputation on Trusted humans, and to improve the look of your reviews badge.

The API request is relatively easy, but you will probably need help from a technical person. If you need help, you can contact us via our contact form.

API Authorization

First, you need to obtain your API token. In order to do so, you can go to the API management of your business dashboard profile, and then scroll to the bottom, to the API Tokens part.

API tokens section

Then you need to click on Create.

Create API token modal

You’ll be prompted to give it:

A token name, that needs to be unique, and just for yourself, as it’s private for internal reference.
The abilities that the token has. For the token review request, it’ll need to be at least “create”.
The token expiration date. If provided, the token will stop working after that date.

Once submitted, you’ll see the API token displayed. This token will only be displayed once, so make sure to copy it!

Copy API token section

This is the token that you will need to use in order to generate the review request. You should share it with the developer that will integrate the logic into your application.

API request

The API request is quite easy to perform. You just have some parameters that need to be sent in order to generate the review request link.

This is the complete request as CURL:

curl --location 'http://trustedhumans.ai/api/v1/reviews/request' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {API_TOKEN}' \
--data-raw '{
    "domain": "{YOUR_DOMAIN}",
    "email": "{CUSTOMER_EMAIL}",
    "name": "{CUSTOMER_NAME}"
}'

Method: POST

Values to be replaced:

API_TOKEN: The API token that you’ve just created
YOUR_DOMAIN: The domain that you want to generate the review request of. For example thustedhumans.ai. It must be claimed by your user.
CUSTOMER_EMAIL: The email address of the customer
CUSTOMER_NAME: The name of the customer (It’ll be publicly displayed like that until changed)

Then, the reply from the server will vary given the result of the operation.

Status 201 (Created)

The review request has been created. It will return a JSON object with the review link.

The example of the reply JSON object is:

{
    "review_request_url": "http://trustedhumans.ai/review/…"
}

The link will only be valid for the next 31 days, and can only be used once.

Status 402 (Payment required)

This status only appears when you’ve run out of requests this month, or your plan doesn’t allow you to perform this API operation.

All requests reset on day 1 of the month.

Status 422 (Validation failed)

This status code means that there was a problem in the parameters provided, it can be either:

domain: The domain parameter is not provided, a string, or it’s not in your claimed profiles. It must exactly match the domain claimed. You can obtain the exact domain if you visit your specific profile, in the URL.
email: The customer email is not provided, it’s longer than 255 characters, or it’s not an email address.
name: The customer name is not provided, it’s not a string, or it’s longer than 128 characters.