API

Fully implement TrustProfile's capabilities

TrustProfile implements an industry standard REST API. The only requirement is that you use the https protocol and identify yourself through your webshop's id and user's api key.

Both can be found on the API page within the dashboard.

Are you using PHP? We offer an API client that can be installed through Composer.


INVITATIONS ADD

Use a POST request to send (or schedule) an invitation.

URL

POST /1.0/invitations.json

GET
parameters
Field Example Default Description
id 1 Required The ID of the webshop.
code "123456789abc123456789" Required Your personal API code.
POST
parameters
Field Example Default Description
email "[email protected]" Required The full e-mail address of the customer to send the invitation to.
order "order123" "" The (optional) order number.
language "en" "<webshop's default>" The (optional) language in ISO-639-1 format.
delay 0 0 The (optional) delay in days (use 0 to send the invitation a.s.a.p.).
customer_name "John Doe" "" The (optional) customer's name.
phone_numbers ["+31612345678"] null The (optional) customer's phone number(s) as an array.
order_total 1500.99 null The (optional) total order amount as a decimal number, formatted with a dot.
order_data "{ "products": [ { "id": "1234", "name": "Product 1", "url": "https:\/\/example.com\/products\/1", "image_url": "https:\/\/example.com\/products\/images\/1", "sku": "PROD1234", "gtin": "12345678s" } ] }" null The (optional) order data as JSON. Product data requires at least: id and name
client "wordpress" null The (optional) name of the software/system the request is originating from.
platform_version "wp-4.9.2-wc-3.2.6" null The (optional) version of the software/system the request is originating from.
plugin_version "1.6.0" null The (optional) version of the code/plugin the request is originating from.
Response
JSON

The response will contain a JSON encoded object with 2 properties: status and message.

{
    "status": "success",
    "message": "Invite successfully added to queue!"
}

The following combinations of status and message are possible:

status message Explanation
success Invitation successfully added to queue! The invitation has successfully been added to the queue.
success Invitation already sent for this order. The combination email and order has already been used for a previous invitation.
error Not all obligated variables are set. One or more of the required variables (id, code and/or email) has/have not been set.
error Incorrect authentication credentials. The combination id and code is invalid.
error Unexpected error while processing. Please contact TrustProfile. An unexpected error has occurred. This will probably only be solvable by the TrustProfile team.
PHP cURL
example
<?php
$id 
1;
$code "123456789abc123456789";

$post = [
    
'email' => '[email protected]',
    
'order' => 'order123',
    
'language' => 'en',
    
'delay' => 0,
    
'customer_name' => 'John Doe',
    
'phone_numbers' => ["+31612345678"],
    
'order_total' => 1500.99,
    
'order_data' => '{
    "products": [
        {
            "id": "1234",
            "name": "Product 1",
            "url": "https:\/\/example.com\/products\/1",
            "image_url": "https:\/\/example.com\/products\/images\/1",
            "sku": "PROD1234",
            "gtin": "12345678s"
        }
    ]
}'
,
    
'client' => 'wordpress',
    
'platform_version' => 'wp-4.9.2-wc-3.2.6',
    
'plugin_version' => '1.6.0',
];

$curl curl_init("https://dashboard.trustprofile.io/api/1.0/invitations.json?id=".$id."&code=".$code);
curl_setopt_array($curl, [
    
CURLOPT_RETURNTRANSFER => true,
    
CURLOPT_FOLLOWLOCATION => true,
    
CURLOPT_POST => true,
    
CURLOPT_POSTFIELDS => http_build_query($post)
]);
$response curl_exec($curl);
if (
$response !== false) {
    
$data json_decode($responsetrue);

    
/*
    $data will look similar to the format below:

    $data = [
        "status" => "success",
        "message" => "Invitation successfully added to queue!"
    ];
    */
} else {
    
// An error occurred
}
?>

INVITATIONS RETRIEVE

Use a GET request to receive a list of date-sorted (newest on top) invitations.

URL

GET /1.0/invitations.json

GET
parameters
Field Example Default Description
id 1 Required The ID of the webshop.
code "123456789abc123456789" Required Your personal API code.
offset 0 0 Offset of returned invitations. For example: an offset of 10 would result in the 10 newest invitations to be excluded.
order 10 10 The maximum amount of returned invitations. The range of the variable is 1 - 100.
Response
JSON

The response will contain a JSON encoded object with 3 properties: status, message and invitations.

{
    "status": "success",
    "message": "Invitations successfully retrieved!",
    "invitations": [{
        "email": "[email protected]",
        "order": "",
        "delay": 0,
        "datetimes": {
            "created": "2021-09-21 03:37:11",
            "scheduled": "2021-09-21 03:37:11",
            "sent": "2021-09-21 05:07:11"
        }
    }, {
        "email": "[email protected]",
        "order": "5468",
        "delay": 2,
        "datetimes": {
            "created": "2021-09-21 03:37:11",
            "scheduled": "2021-09-23 03:37:11",
            "sent": false
        }
    }]
}

The following combinations of status, message and invitations are possible:

status message invitations Explanation
success Invitations successfully retrieved! See example The invitations have successfully been retrieved.
error Not all obligated variables are set. [ ] One or more of the required variables (id, code and/or email) has/have not been set.
error Incorrect authentication credentials. [ ] The combination id and code is invalid.
error Unexpected error while processing. Please contact TrustProfile. [ ] An unexpected error has occurred. This will probably only be solvable by the TrustProfile team.
PHP cURL
example
<?php
$id 
1;
$code "123456789abc123456789";
$offset 0;
$order 10;

$curl curl_init("https://dashboard.trustprofile.io/api/1.0/invitations.json?id=".$id."&code=".$code."&offset=".$offset."&order=".$order);
curl_setopt_array($curl, [
    
CURLOPT_RETURNTRANSFER => true,
    
CURLOPT_FOLLOWLOCATION => true,
]);
$response curl_exec($curl);
if (
$response !== false) {
    
$data json_decode($responsetrue);

    
/*
    $data will look similar to the format below:

    $data = [
        "status" => "success",
        "message" => "Invitations successfully retrieved!",
        "invitations" => See example
    ];
    */
} else {
    
// An error occurred
}
?>

Product Reviews Add

Product reviews are part of Invitations.

In order to create an invitation with products, you have to provide the optional parameter order_data with the relevant product data. See an example in Invitations.

A successfully created invitation with products should appear like the example shown below.

PRODUCT REVIEWS RETRIEVE

Use a GET request to receive a list of product reviews.

URL

GET /1.0/product_reviews.xml

GET
parameters
Field Example Default Description
id 1 Required The ID of the webshop.
code "123456789abc123456789" Required Your personal API code.
detailed 1 Get extra information about product reviews- helpful for syncing product reviews.
last_synced "2021-08-09 17:00:00" "" Get only reviews after given date (Y-m-d H:i:s).
Response
XML
<feed xmlns:vc="http://www.w3.org/2007/XMLSchema-versioning" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://www.google.com/shopping/reviews/schema/product/2.3/product_reviews.xsd">
<version>2.3</version>
<aggregator>
    <name>TrustProfile</name>
</aggregator>
<publisher>
    <name>Example shop</name>
    <favicon>https://example.com/image.png</favicon>
</publisher>
<reviews>
    <review>
        <review_id>12345789</review_id>
        <reviewer>
            <name>John Doe</name>
        </reviewer>
        <review_timestamp>2020-11-16T15:37:54+01:00</review_timestamp>
        <content>Example review text</content>
        <review_url type="singleton"> https://dashboard.trustprofile.io/reviews/view/123456789</review_url>
        <ratings>
            <overall min="1" max="5">5</overall>
        </ratings>
        <products>
            <product>
                <product_ids>
                    <gtins>
                        <gtin>12345678</gtin>
                    </gtins>
                    <skus>
                        <sku>SKU12345678</sku>
                    </skus>
                </product_ids>
                <product_name>Example product name</product_name>
                <product_url>https://example.com/product</product_url>
                <external_id>e12345678</external_id>
            </product>
        </products>
        <is_spam>false</is_spam>
        <email>[email protected]</email>
        <valid>1</valid>
        <deleted/>
        <modified>2020-11-17T15:37:54+01:00</modified>
    </review>
</reviews>
</feed>
PHP cURL
example
<?php
$id 
1;
$code "123456789abc123456789";
$detailed 1;
$last_synced "2021-08-09 17:00:00";

$curl curl_init("https://dashboard.trustprofile.io/api/1.0/product_reviews.xml?id=".$id."&code=".$code."&detailed=".$detailed."&last_synced=".$last_synced);
curl_setopt_array($curl, [
    
CURLOPT_RETURNTRANSFER => true,
    
CURLOPT_FOLLOWLOCATION => true,
]);
$response curl_exec($curl);
if (
$response !== false) {
    
$data simplexml_load_string($response);
} else {
    
// An error occurred
}
?>

RATINGS RETRIEVE

Use a GET request to receive a list of date-sorted (newest on top) ratings.

URL

GET /1.0/ratings.json

GET
parameters
Field Example Default Description
id 1 Required The ID of the webshop.
code "123456789abc123456789" Required Your personal API code.
language "nl" "" The (optional) language in ISO-639-1 format.
offset 0 0 Offset of returned ratings. For example: an offset of 10 would result in the 10 newest ratings to be excluded.
limit 10 10 The maximum amount of returned ratings. The range of the variable is 1 - 100.
Response
JSON

The response will contain a JSON encoded object with 3 properties: status, message and ratings.

{
    "status: "success",
    "message": "Ratings successfully retrieved!",
    "ratings": [{
        "name": "J. Doe",
        "email": "[email protected]",
        "rating": 4,
        "ratings": {
            "shippingtime": 5,
            "customerservice": 3,
            "pricequality": 4,
            "aftersale": 4
        },
        "comment": "Great product, very nice webshop!",
        "date": "2016-02-14",
        "country": "NL",
        "created": "2016-02-14 19:08:00",
        "read": false,
        "quarantine": false
    }, {
        "name": "Jane Doe",
        "email": "[email protected]",
        "rating": 1,
        "ratings": {
            "shippingtime": 1,
            "customerservice": 2,
            "pricequality": 4,
            "aftersale": 1
        },
        "comment": null,
        "date": "2016-02-12",
        "country": "NL",
        "created": "2016-02-12 12:34:12",
        "read": true,
        "quarantine": true
    }]
}

The following combinations of status, message and ratings are possible:

status message ratings Explanation
success Ratings successfully retrieved! See example The ratings has successfully been retrieved.
error Not all obligated variables are set. [ ] One or more of the required variables (id, code and/or email) has/have not been set.
error Incorrect authentication credentials. [ ] The combination id and code is invalid.
error Unexpected error while processing. Please contact TrustProfile. [ ] An unexpected error has occurred. This will probably only be solvable by the TrustProfile team.
PHP cURL
example
<?php
$id 
1;
$code "123456789abc123456789";
$language "nl";
$offset 0;
$limit 10;

$curl curl_init("https://dashboard.trustprofile.io/api/1.0/ratings.json?id=".$id."&code=".$code."&language=".$language."&offset=".$offset."&limit=".$limit);
curl_setopt_array($curl, [
    
CURLOPT_RETURNTRANSFER => true,
    
CURLOPT_FOLLOWLOCATION => true,
]);
$response curl_exec($curl);
if (
$response !== false) {
    
$data json_decode($responsetrue);

    
/*
    $data will look similar to the format below:

    $data = [
        "status" => "success",
        "message" => "Ratings successfully retrieved!",
        "ratings" => See example
    ];
    */
} else {
    
// An error occurred
}
?>

RATINGS RETRIEVE SUMMARY

Use a GET request to receive a summary of all ratings.

URL

GET /1.0/ratings_summary.json

GET
parameters
Field Example Default Description
id 1 Required The ID of the webshop.
code "123456789abc123456789" Required Your personal API code.
Response
JSON

The response will contain a JSON encoded object with 3 properties: status, message and data.

{
    status: "success",
    message: "Rating summary successfully retrieved!",
    data: {
        amount: 26,
        rating_average: 4.194546,
        ratings_average: {
            shippingtime: 4.851756,
            customerservice: 4.658711,
            pricequality: 3.678985,
            aftersale: 4.087224
        }
    }
}

The following combinations of status, message and data are possible:

status message data Explanation
success Ratings summary successfully retrieved! See example The invitations have successfully been retrieved.
error Not all obligated variables are set. null One or more of the required variables (id, code and/or email) has/have not been set.
error Incorrect authentication credentials. null The combination id and code is invalid.
error Unexpected error while processing. Please contact TrustProfile. null An unexpected error has occurred. This will probably only be solvable by the TrustProfile team.
PHP cURL
example
<?php
$id 
1;
$code "123456789abc123456789";

$curl curl_init("https://dashboard.trustprofile.io/api/1.0/ratings_summary.json?id=".$id."&code=".$code);
curl_setopt_array($curl, [
    
CURLOPT_RETURNTRANSFER => true,
    
CURLOPT_FOLLOWLOCATION => true,
]);
$response curl_exec($curl);
if (
$response !== false) {
    
$data json_decode($responsetrue);

    
/*
    $data will look similar to the format below:

    $data = [
        "status" => "success",
        "message" => "Ratings summary successfully retrieved!",
        "data" => See example
    ];
    */
} else {
    
// An error occurred
}
?>

WEBSHOPS RETRIEVE

Use a GET request to receive information about the webshop.

URL

GET /1.0/webshop.json

GET
parameters
Field Example Default Description
id 1 Required The ID of the webshop.
code "123456789abc123456789" Required Your personal API code.
Response
JSON

The response will contain a JSON encoded object with 3 properties: status, message and data.

{
    "status": "success",
    "message": "Webshop details successfully retrieved!",
    "data": {
        "name": "Webshop.com",
        "address": {
            "street": "Stationsweg",
            "housenumber": "1A",
            "postalcode": "1234AB",
            "city": "Amsterdam",
            "country": "Netherlands"
        },
        "logo": "https://dashboard.trustprofile.io/img/logos/1.png",
        "languages": [{
            "name": "Dutch",
            "url": "https://www.trustprofile.com/nl/webshop/TrustProfile_1",
            "iso": "nl",
            "all": true,
            "main": true
        }, {
            "name": "English",
            "url": "https://www.trustprofile.com/webshop/TrustProfile_1",
            "iso": "en",
            "all": false,
            "main": false
        }]
    }
}

The following combinations of status, message and data are possible:

status message data Explanation
success Webshop details successfully retrieved! See example The webshop has successfully been retrieved.
error Incorrect authentication credentials. [ ] The combination id and code is invalid.
error Unexpected error while processing. Please contact TrustProfile. [ ] An unexpected error has occurred. This will probably only be solvable by the TrustProfile team.
PHP cURL
example
<?php
$id 
1;
$code "123456789abc123456789";

$curl curl_init("https://dashboard.trustprofile.io/api/1.0/webshop.json?id=".$id."&code=".$code);
curl_setopt_array($curl, [
    
CURLOPT_RETURNTRANSFER => true,
    
CURLOPT_FOLLOWLOCATION => true,
]);
$response curl_exec($curl);
if (
$response !== false) {
    
$data json_decode($responsetrue);

    
/*
    $data will look similar to the format below:

    $data = [
        "status" => "success",
        "message" => "Webshop details successfully retrieved!",
        "data" => See example
    ];
    */
} else {
    
// An error occurred
}
?>

JAVASCRIPT SIDEBAR + TOOLTIP

Our sidebar and tooltips can be programmatically configured by altering the appropriate JavaScript variables. Please note that both can also be configured without any programming knowledge from the corresponding page within the dashboard. The JavaScript variables will always overwrite any configuration set via the dashboard, therefore we recommend to use the configuration option in the dashboard if you want it to apply to all pages.

SIDEBAR The sidebar is a small, but powerful element which will be displayed on the side of the browser, always in view. A popup will open when it's clicked, dislaying detailed information, reviews and much more.

TOOLTIP The tooltip will appear when the mouse hovers over an element with the following class name "trustprofilePopup", "trustprofileReviews" and "trustprofileAddReview" or over a widget. When you click on one of these elements a popup will be displayed.

Code
<script>
  //_trustprofile_sidebar = true;
  //_trustprofile_sidebar_position = "left";
  //_trustprofile_sidebar_top = "300";
  //_trustprofile_sidebar_theme = "dark";
  //_trustprofile_mobile = "top_bar";
  //_trustprofile_mobile_tab = "left";
  //_trustprofile_tooltip = true;
  //_trustprofile_language = <webshop's default>;
</script>
<script>(function(n,r){var e=document.createElement("script");e.async=!0,e.src=n+"/sidebar.js?id="+r+"&c="+c(10,r);var t=document.getElementsByTagName("script")[0];t.parentNode.insertBefore(e,t);function c(s,i){var o=Date.now(),a=s*6e4,_=(Math.sin(i)||0)*a;return Math.floor((o+_)/a)}})("https://dashboard.trustprofile.io","<webshop's ID>");</script>

The code shows the sidebar and enables the tooltips on page load. You have to change <webshop's ID> to the ID of the webshop you want to show the sidebar for. Also it has all optional configuration variables commented out.

Tooltip

Any element (preferably <a> elements) given a "TrustProfile", "trustprofilePopup" or "trustprofileReviews" class will show a trustprofileAddReview tooltip displaying your rating, reviews count and earned badges experience on hover. When clicked, a popup window will be shown which either equals the sidebars popup or allows the consumer to share their experience directly. This depends on the class chosen, see below for more information.

Note! When you disable the tooltip, clicking on elements with one of the classes listed below will still open their popup.

trustprofilePopup class

Opens the sidebars popup displaying both TrustProfiles key points and the webshop details. Just like the sidebars popup, it allows the consumer to view the webshops reviews without leaving the popup.

Example <a href="#" class="trustprofilePopup ">We are verified by TrustProfile</a>

trustprofileReviews class

Opens the sidebars popup displaying the reviews. Just like the sidebars popup, it allows the consumer to view TrustProfiles key points and webshop details without leaving the popup.

Example <a href="#" class="trustprofileReviews ">View reviews</a>

trustprofileAddReview class

Opens a popup with a form which allows a consumer to share their experience. This popup is similar to the popup presented when clicking "How do you rate this web store?" on your member page.

Example <a href="#" class="trustprofileAddReview ">How do you rate this web store?</a>
Variables
Name Values Default Description
_trustprofile_sidebar true or false true Enables the sidebar.
_trustprofile_sidebar_position "left" or "right" "left" On which side of the screen to show the non-mobile sidebar.
_trustprofile_sidebar_top String with amount in pixels (e.g. "100") or a percentage (e.g. "20%") "300" The amount of offset from the top of the screen.
_trustprofile_sidebar_theme "dark" or "light" "dark" The theme of the sidebar.
_trustprofile_mobile "none", "top_bar" or "top", "top_left", "top_right", "top_manual", "bottom", "bottom_left", "bottom_right", "bottom_manual" "top_bar"

Enables the sidebar for mobile visitors and selects its type and position (when relevant).

If set to "none" then the mobile sidebar is disabled.

The value "top_bar" enables the "Top Bar" which always shows on the top of your page.
Note: This option doesn't work if you have a header or an element with position: fixed;!

All other options enable the mobile sidebar and sets its position.
_trustprofile_mobile_tab "left", "center" or "right" "left" Changes the position of the mobile sidebar tab, based on the tooltip's width. This option is not available if _trustprofile_mobile is set to "top_bar".
_trustprofile_tooltip true or false true Enables the tooltip.
_trustprofile_language The ISO-639-3 value of one of our supported languages (e.g. "nld"), "url", "html" or "browser" <webshop's default> The language of the sidebar and its popup. Besides setting a specific language, you can also choose to let us decide what language is required either by analysing the url ("url"), language attribute ("html") or preferred language by the visitor ("browser").

JAVASCRIPT WIDGET

Our widget enables you to show your reviews directly on your webshop. The color and other physical properties are configurable to match your webshop's style. We strongly recommend to use the widget configuration in the dashboard, also as a visual tool to aid the programmatic configuration.

Code
<iframe src="https://dashboard.trustprofile.com/webshops/widget_html?id=<webshop's ID>&layout=new_default&theme=dark&color=%23ea0e8b&show=yes&view=slider&amount=6&width=manual&width_amount=280px&height=250px&interval=5000&language=nld" scrolling="no" class="wwk-widget-iframe wwk-widget--new_default wwk-widget--new_default--dark" style="border: 0; height: 250px!important; width: 280px!important;"></iframe>

The code places the widget on the location where the code is placed. You should replace <webshop's ID> with the ID of the webshop for which the widget should be displayed.
The width and height of the iframe have to be changed, based on widget's dimensions. They must be the same as the parameters.
You can modify your widget's styles with adding a css parameter. Find it in the table for more information.

Parameters
Name Values Default Description Layouts
id Numeric Required The ID of the webshop for which you want to show the widget. All
layout "new_default", "new_badges" etc. Required The layout of the widget. All
theme "light" or "dark" Required The type of theme/background. new_default new_badges new_button-text new_button-stars new_button_logo new_button_logo-score new_button_logo-sm new_balloon
color String with CSS color code (e.g. "#ea0e8b" or "rgb(234, 14, 139)") Required The color of some prominent elements of the widget. new_default new_badges new_button-text new_button-stars new_button_logo new_button_logo-score new_button_logo-sm new_balloon
show "yes" or "no" Required Displaying of customer reviews. When disabled, the widget is shortened in height. new_default
view "slider" or "list" Required The method with which the customer reviews are shown. new_default
amount Numeric (1-6 scale) Required The amount of customer reviews to be shown. new_default
width "auto" or "manual" Required The widget's width; either filling ("auto") or fixed/percentual ("manual"). new_default new_badges new_button-text new_button-stars new_button_logo new_button_logo-score new_button_logo-sm new_balloon
width_amount String with CSS width (e.g. "100px" or "70%") Required The width in case width has been set to "manual". new_default new_badges new_button-text new_button-stars new_button_logo new_button_logo-score new_button_logo-sm new_balloon
height Numeric Required Height of the widget in pixels. All
interval Numeric Required The amount of milliseconds before switching to the next customer review when view is set to "slider". new_default
language Numeric Required The language of the widget. The following values can be used:
"nld" (Dutch)
"eng" (English)
"deu" (German)
"fra" (French)
"spa" (Spanish)
"ita" (Italian)
You need a multi language package and have the language enabled for your webshop. Otherwise, it defaults to English.
new_default new_badges new_button-text new_button-stars new_button_logo new_button_logo-score new_button_logo-sm new_balloon
css CSS or URL Optional With this parameter you can add your own CSS to the widget without changing the styles of your website.
There are two ways to do this:
Using CSS rules
Add as many rules as you want using the standard CSS syntax.
Example: css=body{background:blue;}
Import a CSS file
Example: css=https://mywebsite.com/custom-widget.css
Note: In most cases you should add "!important" for every rule.
All