MENÜ
Code-examples / Return values

ProvenExpert API

Introduction

With the ProvenExpert API you can create and edit ProvenExpert profiles, create surveys and invitation links to surveys, request the overall rating and number of ratings for profiles and create HTML code for ratings seals.

To use the ProvenExpert API, a ProvenExpert profile with the respective payment package is required.

Available Packages:

PLUS: API basic functions

PREMIUM: API basic functions & rating endpoint

ENTERPRISE: All API functions

API URL structure

Beispielhafter API-Aufruf mit PHP

<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.provenexpert.com/api/v1/auth/url/get');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, '<API-ID>:<API-KEY>');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

$json = curl_exec($ch);
$result = json_decode($json);

curl_close($ch);

URL fields

The URL is composed of the API endpoint, the API version and the service and function names.

Field Value
API endpoint https://www.provenexpert.com/api/
API version v1
Service auth/url
Function get

Examples

https://www.provenexpert.com/api/v1/profile/create

https://www.provenexpert.com/api/v1/rating/summary/get

Versions

Currently, the API is only available in version 1.

HTTP method

All API calls must be sent as POST requests.

Data format

The ProvenExpert API returns all data in JSON.

Authentication

Authentication takes place via Basic Auth with an API ID and an API key. These are embedded in the ProvenExpert account.

Request structure

Beispielhafte Request-Datenstruktur in PHP

<?php

$data = array(
    'proxyUser' => array(
        'email' => 'user@example.com'
    ),
    'limit'  => 50,
    'offset' => 0,
    'data'   => array(
        // ...
    )
);

In general, all fields in an API request are optional. However, some fields need to be entered depending on the API function used. All mandatory fields are marked with a star (*) in this documentation.

Data field Description Type
proxyUser Proxy user Array
proxyUser.id external UserId (see profile/create - externalData.userId) String
oder  
proxyUser.email Email address for the profile String
   
limit Number of data sets returned Integer (max. 100)
offset Pagination Integer
data Request data Array

Proxy user

If a proxy user is identified (parameter proxyUser), the API call is executed within this user context. This makes it possible to supervise several different profiles with just one API access.

Return values

Succesful request

{
    "status" : "success"
}

Succesful request

Each API answer contains the field status, which contains the value success in successful cases. If a fault occurs, the field error will be returned. Additionally data will be returned in further fields, depending on the API function.

Some functions will return the field notes. In this array notes are listed which may indicate, for instance, that an unknown data field has been entered or an over-long field has been shortened.

Incorrect request

{
    "status" : "error",
    "errors" : [
        "malformed field: email"
    ]
}

Incorrect request

If the field status contains the value error, the errors field will be returned. This array includes one or multiple errors.

Profiles

profile/create

Request

<?php

$data = array(
    'data' => array(
        'email'       => 'user@example.com',
        'company'     => 'company ABC',
        'description' => 'company ABC offers services',
        'openingHours' => array(
            'requestOnly' => 0,
            'mon' => array(
                'start1' => '0900',
                'end1' => '2200',
            ),
            'tue' => array(
                'openDay' => 0
            ),
            'wed' => array(
                'start1' => '0900',
                'end1' => '1130',
                'start2' => '1200',
                'end2' => '1400',
            ),                    
        )
    )
);

Response

{
    "status"         : "success",
    "profile"        : {
        "created"     : 1453111042,
        "email"       : "user@example.com",
        "profileUrl"  : "<link>",
        "public"      : 0,
        "company"     : "company ABC",
        "description" : "company ABC offers services",
        "openingHours" : {
            "days"     : {
                "weekday1" : {
                    "start1" : "0900",
                    "end1"   : "2200"
                },
                "weekday3" : {
                    "start1" : "0900",
                    "end1"   : "1130",
                    "start1" : "1200",
                    "end1"   : "1400"
                }
            }
        }
    },
    "login" : {
        "url"    : "<link>",
        "expire" : 1452784796
    }
}

Please note: this function is only available with the ENTERPRISE package.

Creates a new ProvenExpert profile.

A company or personal profile can be created.

The profile and a Single Sign On URL will be returned.

Request

Name Bescheibung Typ Default
email * Email address String
   
company * FCompany name (creates a company profile) String (min. 3 characters)
or  
firstname * First name (creates a personal profile) String (min. 2 characters)
lastname * Surname (creates a personal profile) String (min. 2 characters)
   
password Password (if not set a random password will be allocated) String (min. 6 characters)
description Activity description, String (max. 80 characters)
about Profile description String (max. 10.000 characters)
tags Offer tags (each separated with a comma) String (max. 600 characters)
avatarUrl URL for profile image (JPG or PNG, max. 5 MB) String
public Profile is made public Integer (characters: yes; 0: no) 0
imprint Imprint String (max. 10,000 Zeichen)
   
externalData External data Array
externalData.userId Foreign UserId (e.g. from the CMS of the API user) String
   
contact Contact details Array
contact.person Contact person (only used in company profiles) String
contact.company Company name (only used in personal profiles) String
contact.street Street name and house no. String
contact.zip Zip code String
contact.city City/Town String
contact.country Country code String (de;at;ch)
contact.email Contact email address String
contact.phone Landline number String
contact.mobile Mobile number String
contact.fax Fax number String
   
websites List with profile owner websites Array (max. 5 entries)
websites.[n] URL and name of the website Array
websites.[n].label Name of link String
websites.[n].url URL of the website String
   
social List with URLs for profiles from social networks Array (max. 10 entries)
social.[n] URL of profile String
   
externalRatings List with URLs for profiles on rating portals Array (max. 100 entries)
externalRatings.[n] URL of profile (e.g.: yelp) String
   
openingHours opening hours Array
openingHours.requestOnly appointments on request only (possible values 1: yes; 0: no) Refers to entire week, all other settings ignored if ‘1’) Integer
openingHours.[n].start1 1st start time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. Optionally with 'pm’ or 'am’ : '0930pm’) String
openingHours.[n].end1 1st end time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. Optionally with 'pm’ or 'am’ : '0930pm’) String
openingHours.[n].start2 2nd start time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. Optionally with 'pm’ or 'am’ : '0930pm’) String
openingHours.[n].end2 2nd end time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. Optionally with 'pm’ or 'am’ : '0930pm’) String
openingHours.[n].openDay closed all day long. (possible values 'on’, 'off’, all other settings ignored if 'off’) String

Response

Datenfeld Beschreibung Typ
profile List with profile data Array
profile.created Timestamp of creation Integer
profile.email Email for the profile String
profile.profileUrl URL for the profile String
profile.public Is the profile public? Integer (0: no; 1: yes)
profile.company Company name (for company profile only) String
profile.firstname First name (for personal profile only) String
profile.lastname Surname (for personal profile only) String
profile.description Activity description String
login Data for login Array
login.url Link for login String
login.expire Timestamp representing link expiration date Integer
profile.avatarUrl avatar picture url String
profile.imprint imprint String
   
profile.externalData external data Array
profile.externalData.userId foreign UserId (for ex. from a clients CMS) String
   
profile.tags SEO tags (jcomma-separated) String
profile.about profile description String
profile.avatarUrl profile picture description String
   
profile.contact contact data Array
profile.contact.person contact person String
profile.contact.company company name String
profile.contact.street street and number String
profile.contact.zip ZIP code String
profile.contact.city city String
profile.contact.country country code String (ISO 3166 ALPHA-2)
profile.contact.email contact email String
profile.contact.phone phone number String
profile.contact.mobile mobile phone String
profile.contact.fax fax String
   
profile.social list of social network profile urls Array
profile.social.[n] profile url String
   
profile.openingHours opening hours Array
profile.openingHours.requestOnly appointments on request only (possible values 1: yes; 0: no) Refers to entire week) Integer
profile.openingHours.[n] Settings for one day (possible values for n : mon, tue, wed, thu, fri, sat, sun). Array
profile.openingHours.[n].start1 1st start time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].end1 1st end time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].start2 2nd start time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].end2 2nd end time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].openDay closed all day long. (possible values 'on’, 'off’) String

profile/update

Request

<?php

$data = array(
    'data' => array(
         'email' => 'webmaster@example.com',
        'openingHours' => array(
            'requestOnly' => 0,
            'mon' => array(
                'start1' => '0930',
                'end1' => '1200',
            ),
            'sat' => array(
                'openDay' => 1,
                'start1' => '0930am',
                'end1' => '1100am',
            ),
            'wed' => array(
                'openDay' => 0,
            ),
            'sun' => array(
                'start1' => '0930',
                'end1' => '1100',
            )
        )
    )
);

Response

{
    "status"  : "success",
    "profile" : {
        "created"    : 1453111042,
        "email"      : "webmaster@example.com",
        "profileUrl" : "<link>",
        "public"     : 0,
        "company"    : "company ABC"
    }
}

Edits an existing ProvenExpert profile.

Only the fields that have to be changed need to be entered. A blank string must be entered in order to delete a field. Arrays with numerical indices can only be edited as a whole (e.g. websites, social), whereas fields for associative arrays (e.g. contact) can be edited individually.

The edited profile will be returned.

Request

Name Description Type
email Email address String
password Password String (min. 6 characters)
description Activity description, String (max. 80 characters)
about Profile description String (max. 10.000 characters)
tags Offer tags (each separated with a comma) String (max. 600 characters)
avatarUrl URL for profile image (JPG or PNG, max. 5 MB) String
public Profile is made public Integer (1: yes; 0: no)
imprint Imprint String (max. 10.000 characters)
   
externalData External data Array
externalData.userId Foreign UserId (e.g. from the CMS of the API user) String
   
contact Contact details Array
contact.person Contact person (only used in company profiles) String
contact.company Company name (only used in personal profiles) String
contact.street Street name and house no. String
contact.zip Zip code String
contact.city City/Town String
contact.country Country code String (de;at;ch)
contact.email Contact email address String
contact.phone Landline number String
contact.mobile Mobile number String
contact.fax Fax number String
   
websites List with profile owner websites Array (max. 5 entries)
websites.[n] URL and name of the website Array
websites.[n].label Name of link String
websites.[n].url URL of the website String
   
social List with URLs for profiles from social networks Array (max. 10 entries)
social.[n] URL of profile String
   
externalRatings List with URLs for profiles on rating portals Array (max. 100 entries)
externalRatings.[n] URL of profile (e.g.: yelp) String
   
openingHours opening hours Array
openingHours.requestOnly appointments on request only (possible values 1: yes; 0: no) Refers to entire week, all other settings ignored if ‘1’) Integer
openingHours.[n].start1 1st start time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. Optionally with 'pm’ or 'am’ : '0930pm’) String
openingHours.[n].end1 1st end time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. Optionally with 'pm’ or 'am’ : '0930pm’) String
openingHours.[n].start2 2nd start time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. Optionally with 'pm’ or 'am’ : '0930pm’) String
openingHours.[n].end2 2nd end time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. Optionally with 'pm’ or 'am’ : '0930pm’) String
openingHours.[n].openDay closed all day long. (possible values 'on’, 'off’, all other settings ignored if 'off’) String

Response

Data field Description Type
profile List with profile data Array
profile.created Timestamp of creation Integer
profile.email Email for the profile String
profile.profileUrl URL for the profile String
profile.public Is the profile public? Integer (0: no; 1: yes)
profile.company Company name (for company profile only) String
profile.firstname First name (for personal profile only) String
profile.lastname Last name (for personal profile only) String
profile.description Activity description String
profile.avatarUrl avatar picture url String
profile.imprint imprint String
   
profile.externalData external data Array
profile.externalData.userId foreign UserId (for ex. from a clients CMS) String
   
profile.tags SEO tags (jcomma-separated) String
profile.about profile description String
profile.avatarUrl profile picture description String
   
profile.contact contact data Array
profile.contact.person contact person String
profile.contact.company company name String
profile.contact.street street and number String
profile.contact.zip ZIP code String
profile.contact.city city String
profile.contact.country country code String (ISO 3166 ALPHA-2)
profile.contact.email contact email String
profile.contact.phone phone number String
profile.contact.mobile mobile phone String
profile.contact.fax fax String
   
profile.social list of social network profile urls Array
profile.social.[n] profile url String
   
profile.openingHours opening hours Array
profile.openingHours.requestOnly appointments on request only (possible values 1: yes; 0: no) Refers to entire week) Integer
profile.openingHours.[n] Settings for one day (possible values for n : mon, tue, wed, thu, fri, sat, sun). Array
profile.openingHours.[n].start1 1st start time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].end1 1st end time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].start2 2nd start time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].end2 2nd end time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].openDay closed all day long. (possible values 'on’, 'off’) String

profile/get

Request

// no additional data

Response

{
    "status" : "success",
    "profile" : {
        "created"    : 1453111042,
        "email"      : "user1@example.com",
        "profileUrl" : "<link>",
        "public"     : 0,
        "company"    : "company ABC"
    }
}

Returns your own profile.

Response

Data field Description Type
profile List with profile data Array
profile.created Timestamp of creation Integer
profile.email Email for the profile String
profile.profileUrl URL for the profile String
profile.public Is the profile public? Integer (0: no; 1: yes)
profile.company Company name (for company profile only) String
profile.firstname First name (for personal profile only) String
profile.lastname Last name (for personal profile only) String
profile.description Activity description String
profile.avatarUrl avatar picture url String
profile.imprint imprint String
   
profile.externalData external data Array
profile.externalData.userId foreign UserId (for ex. from a clients CMS) String
   
profile.tags SEO tags (jcomma-separated) String
profile.about profile description String
profile.avatarUrl profile picture description String
   
profile.contact contact data Array
profile.contact.person contact person String
profile.contact.company company name String
profile.contact.street street and number String
profile.contact.zip ZIP code String
profile.contact.city city String
profile.contact.country country code String (ISO 3166 ALPHA-2)
profile.contact.email contact email String
profile.contact.phone phone number String
profile.contact.mobile mobile phone String
profile.contact.fax fax String
   
profile.social list of social network profile urls Array
profile.social.[n] profile url String
   
profile.openingHours opening hours Array
profile.openingHours.requestOnly appointments on request only (possible values 1: yes; 0: no) Refers to entire week) Integer
profile.openingHours.[n] Settings for one day (possible values for n : mon, tue, wed, thu, fri, sat, sun). Array
profile.openingHours.[n].start1 1st start time (possible values ‘0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].end1 1st end time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].start2 2nd start time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].end2 2nd end time (possible values '0000’, '0030’, '0100’, '0130’ … '2400’. String
profile.openingHours.[n].openDay closed all day long. (possible values 'on’, 'off’) String

profile/children

Request

// no additional data

Response

{
    "status" : "success",
    "profiles" : [
        {
            "created"    : 1453111042,
            "email"      : "user1@example.com",
            "profileUrl" : "<link>",
            "public"     : 0,
            "company"    : "company ABC"
        },
        {
            "created"    : 1453111042,
            "email"      : "user2@example.com",
            "profileUrl" : "<link>",
            "public"     : 1,
            "firstname"  : "John",
            "lastname"   : "Doe"
        }
    ]
}

In an Enterprise profile, returns all the subprofiles from the next level down. In a normal profile, all profiles that were created along with the main profile will be returned.

Response

Data field Description Type
profiles List with all profiles Array
profiles.[n] Data set for a profile Array
profiles.[n].created Timestamp of creation Integer
profiles.[n].email Email for the profile String
profiles.[n].profileUrl URL for the profile String
profiles.[n].public Is the profile public? Integer (0: no; 1: yes)
profiles.[n].company Company name (for company profile only) String
profiles.[n].firstname First name (for personal profile only) String
profiles.[n].lastname Last name (for personal profile only) String
profiles.[n].description Activity description String

profile/settings/update

Request

<?php

$data = array(
    'data' => array(
         'public' => 1,
         'mails'  => array(
              'reporting' => 0
         )
    )
);

Response

{
    "status"  : "success",
    "settings" : {
        "public"  : 1,
        "privacy" : {
            "ratingButton"          : 1,
            "ratingButtonWithCode"  : 1,
            "showVoterData"         : 1,
            "showCompanyName"       : 1,
            "showName"              : 1,
            "showLastname"          : 1,
            "contactButton"         : 1,
            "showTopCompetences"    : 1,
            "showAllCompetences"    : 1,
            "showRatingCompetences" : 1,
            "showExternalRatings"   : 1
        },
        "notify"  : {
            "rating"         : 1,
            "contactRequest" : 1,
            "ratingRequest"  : 1,
            "service"        : 1,
            "externalRating" : 1
        },
        "mails"   : {
            "newsletter" : 1,
            "reporting"  : 0
        }
    }
}

Edits the profile settings.

Only values which need to be changed should be entered. All other settings should remain unchanged.

All current profile settings will be returned.

Response

Name Description Type
public Is the profile public? Integer (0: no; 1: yes)
   
privacy List of privacy settings Array
privacy.ratingButton Profile visitors can evaluate me Integer (0: no; 1: yes)
privacy.ratingButtonWithCode Only allow rating after my approval Integer (0: no; 1: yes)
privacy.showVoterData Show evaluator information Integer (0: no; 1: yes)
privacy.showCompanyName Show company name Integer (0: no; 1: yes)
privacy.showName Show first and last name Integer (0: no; 1: yes)
privacy.showLastname Show full last name Integer (0: no; 1: yes)
privacy.contactButton Visitors can write me a message Integer (0: no; 1: yes)
privacy.showTopCompetences Show my top competencies Integer (0: no; 1: yes)
privacy.showAllCompetences Show all evaluated competencies Integer (0: no; 1: yes)
privacy.showRatingCompetences Show competencies when clicking on categories Integer (0: no; 1: yes)
privacy.showExternalRatings Show my ratings from other sources Integer (0: no; 1: yes)
   
notify List of notification settings Array
notify.rating New ratings on ProvenExpert.com Integer (0: no; 1: yes)
notify.ratingRequest Requests for rating Integer (0: no; 1: yes)
notify.contactRequest Contact requests Integer (0: no; 1: yes)
notify.service Service info from ProvenExpert Integer (0: no; 1: yes)
notify.externalRating New ratings from other sources Integer (0: no; 1: yes)
   
mails List with additional email settings Array
mails.reporting Current status information and tips for my ProvenExpert profile (Reporting) Integer (0: no; 1: yes)
mails.newsletter Interesting product functions, news and special offers from ProvenExpert (Newsletter) Integer (0: no; 1: yes)

profile/settings/get

Request

// no additional data

Response

{
    "status"  : "success",
    "settings" : {
        "public"  : 1,
        "privacy" : {
            "ratingButton"          : 1,
            "ratingButtonWithCode"  : 1,
            "showVoterData"         : 1,
            "showCompanyName"       : 1,
            "showName"              : 1,
            "showLastname"          : 1,
            "contactButton"         : 1,
            "showTopCompetences"    : 1,
            "showAllCompetences"    : 1,
            "showRatingCompetences" : 1,
            "showExternalRatings"   : 1
        },
        "notify"  : {
            "rating"         : 1,
            "contactRequest" : 1,
            "ratingRequest"  : 1,
            "service"        : 1,
            "externalRating" : 1
        },
        "mails"   : {
            "newsletter" : 1,
            "reporting"  : 1
        }
    }
}

Returns the profile settings.

Response

Name Description Type
public Is the profile public? Integer (0: no; 1: yes)
   
privacy List of privacy settings Array
privacy.ratingButton Profile visitors can evaluate me Integer (0: no; 1: yes)
privacy.ratingButtonWithCode Only allow rating after my approval Integer (0: no; 1: yes)
privacy.showVoterData Show evaluator information Integer (0: no; 1: yes)
privacy.showCompanyName Show company name Integer (0: no; 1: yes)
privacy.showName Show first and last name Integer (0: no; 1: yes)
privacy.showLastname Show full last name Integer (0: no; 1: yes)
privacy.contactButton Visitors can write me a message Integer (0: no; 1: yes)
privacy.showTopCompetences Show my top competencies Integer (0: no; 1: yes)
privacy.showAllCompetences Show all evaluated competencies Integer (0: no; 1: yes)
privacy.showRatingCompetences Show competencies when clicking on categories Integer (0: no; 1: yes)
privacy.showExternalRatings Show my ratings from other sources Integer (0: no; 1: yes)
   
notify List of notification settings Array
notify.rating New ratings on ProvenExpert.com Integer (0: no; 1: yes)
notify.contactRequest Requests for rating Integer (0: no; 1: yes)
notify.ratingRequest Contact requests Integer (0: no; 1: yes)
notify.service Service info from ProvenExpert Integer (0: no; 1: yes)
notify.externalRating New ratings from other sources Integer (0: no; 1: yes)
   
mails List with additional email settings Array
mails.reporting Current status information and tips for my ProvenExpert profile (Reporting) Integer (0: no; 1: yes)
mails.newsletter Interesting product functions, news and special offers from ProvenExpert (Newsletter) Integer (0: no; 1: yes)

Widget

widget/create

Request

<?php

$data = array(
    'data' => array(
        'type'     => 'portrait',
        'width'    => 180,
        'feedback' => 1,
        'slider'   => 0
    )
);

Response

{
    "status" : "success",
    "html"   : "<html>"
}

Creates a new ratings seal. Returns HTML code for the seal.

Request

There are the following types:

Type Description
portrait Ratings seal vertical
square Ratings seal quadratic
landscape Ratings seal horizontal
circle seal of quality
logo ProvenExpert logo
bar Ratings seal at the bottom edge of the browser
landing rating widget

Options for the ratings seal vertical

ratings seal vertical ratings seal as slider

Data field Description Type Default
type * Type of widget String (portrait)
width * Ratings seal width in pixels Integer (90 - 250)
feedback Display customer votes Integer (0: no; 1: yes) 0
slider Ratings seal on browser margin Integer (0: no; 1: yes)
fixed Dock seal on browser margin Integer (0: no; 1: yes)
origin Distance of seal measured from top or bottom browser margin? String (top; bottom)
position Pixel distance of seal from top or bottom browser margin Integer
side Browser side on which ratings seal is docked String (left; right)
viewport Browser width in pixels from which seal is displayed Integer

Options for the ratings seal quadratic

Bewertungssiegel quadratisch

Data field Description Type Default
type * Type of widget String (square)
width * Ratings seal width in pixels Integer (90 - 300)
feedback Display customer votes Integer (0: no; 1: yes) 0
slider Ratings seal on browser margin Integer (0: no; 1: yes)
fixed Dock seal on browser margin Integer (0: no; 1: yes)
origin Distance of seal measured from top or bottom browser margin? String (top; bottom)
position Pixel distance of seal from top or bottom browser margin Integer
side Browser side on which ratings seal is docked String (left; right)
viewport Browser width in pixels from which seal is displayed Integer

Options for the ratings seal horizontal

Bewertungssiegel quer

Data field Description Type Default
type * Type of widget String (landscape)
width * Ratings seal width in pixels Integer (110 - 300)
feedback Display customer votes Integer (0: no; 1: yes) 0
slider Ratings seal on browser margin Integer (0: no; 1: yes)
fixed Dock seal on browser margin Integer (0: no; 1: yes)
origin Distance of seal measured from top or bottom browser margin? String (top; bottom)
position Pixel distance of seal from top or bottom browser margin Integer
side Browser side on which ratings seal is docked String (left; right)
viewport Browser width in pixels from which seal is displayed Integer

Options for the seal of quality

seal of quality

Data field Description Type Default
type * Type of widget String (circle)
width * Ratings seal width in pixels Integer (60 - 300)
fixed dock seal of quality on browser margin Integer (0: no; 1: yes)
origin Distance of seal measured from top or bottom browser margin? String (top; bottom)
position Pixel distance of seal from top or bottom browser margin Integer
side Browser side on which ratings seal is docked String (left; right)
viewport Browser width in pixels from which seal is displayed Integer

ProvenExpert logo

Data field Description Type Default
type * Type of widget String (logo)
width * Ratings seal width in pixels Integer (100 - 300)
style Color of logo String (black;white) black
fixed dock ProvenExpert logo on browser margin Integer (0: no; 1: yes)
origin Distance of seal measured from top or bottom browser margin? String (top; bottom)
position Pixel distance of seal from top or bottom browser margin Integer
side Browser side on which ratings seal is docked String (left; right)
viewport Browser width in pixels from which seal is displayed Integer

Options for the ratings seal at the bottom edge of the browser

ratings seal at the bottom edge of the browser

Data field Description Type Default
type * Type of widget String (bar)
style Background color String (black;white) white
feedback Display customer votes Integer (0: no; 1: yes) 0

Options for the rating widget

rating widget

Data field Description Type Default
type * Type of widget String (landing)
style Color of the header String (black;white) black
avatar Show profile image Integer (0: no; 1: yes) 1
feedback Display customer votes Integer (0: no; 1: yes) 1
competence Show top competencies Integer (0: no; 1: yes) 1

Response

Data field Description Type
html HTML code of the ratings seals String

Surveys

survey/create

Request

<?php

$data = array(
    // ...
    'data' => array(
        'name'          => 'new survey',
        'pos'           => 1,
        'posLabel'      => 'branch 5',
        'posLogoBase64' => 'data:image/png;base64,iVBORw0...'
    )
);

// or

$data = array(
    // ...
    'data' => array(
        'name'     => 'new survey',
        'pos'      => 0
    )
);

Response

{
    "status" : "success",
    "survey" : {
        "code"      : "OEG36T",
        "name"      : "Name of survey",
        "created"   : 1396609449,
        "active"    : 1,
        "url"       : "<link>",
        "pos"       : 0,
        "qr"        : "<link>",
        "printPng"  : "<link>",
        "printPdf"  : "<link>"
    }
}

Creates a new survey.

Request

Data field Description Type Default
name * Name of survey String
pos Is it a Point of Sale survey? Integer (0: no; 1: yes) 0
posLabel Label for the POS template String
posLogoUrl URL for POS logo (JPG or PNG, max. 5 MB) String
posLogoBase64 Logo as Data URL string (Base64) String

Response

Data field Description Type
survey Dataset from the survey Array
survey.code Survey code String
survey.name Name of survey String
survey.created Timestamp of creation Integer
survey.activated Is the survey active? Integer (0: no; 1: yes)
survey.url Survey URL String
survey.pos Is it a Point of Sale survey? Integer (0: no; 1: yes)
survey.qr Link from QR code image String
survey.printPng Link to business card template (PNG) String
survey.printPdf Link to business card template (PDF) String

Point of Sale survey (POS)

In order to create Point of Sale surveys, a setting in the user account is required. This can only be done via ProvenExpert customer support. In a Point of Sale survey, the fields qr, printPng and printPdf are empty.

You can add the logo for the POS survey either via a URL or per data URL string.

The data URL string must have the following structure (see Data-URL):

survey/update

Request

<?php

$data = array(
    // ...
    'filter' => array(
        'code' => 'FR6JZG'
    ),
    'data'   => array(
        'active' => 0
    )
);

Response

{
    "status" : "success",
    "surveys" : {
        "code"      : "FR6JZG",
        "name"      : "Name of survey",
        "created"   : 1396609449,
        "active"    : 1,
        "url"       : "<link>",
        "pos"       : 0,
        "qr"        : "<link>",
        "printPng"  : "<link>",
        "printPdf"  : "<link>"
    }
}

Updates a survey.

Request

Filter field Description Type
code * Survey code of the survey you want to change String
Data field Description Type
active De/activates the survey Integer (0: no; 1: yes)
posLabel Label for the POS template String
posLogoUrl URL for POS logo (JPG or PNG, max. 5 MB) String
posLogoBase64 Logo as Data URL string (Base64) String

Response

Data field Description Type
survey Dataset from the survey Array
survey.code Survey code String
survey.name Name of survey String
survey.created Timestamp of creation Integer
survey.activated Is the survey active? Integer (0: no; 1: yes)
survey.url Survey URL String
survey.pos Is it a Point of Sale survey? Integer (0: no; 1: yes)
survey.qr Link from QR code image String
survey.printPng Link to business card template (PNG) String
survey.printPdf Link to business card template (PDF) String

Point of Sale survey

In a Point of Sale survey, the fields qr, printPng and printPdf are empty.

You can add the logo for the POS survey either via a URL or per data URL string.

The data URL string must have the following structure (see Data-URL):

survey/get

Request

// no additional data

Response

{
    "status"  : "success",
    "surveys" : {
        "OEG36T" : {
            "code"      : "OEG36T",
            "name"      : "Name of survey",
            "created"   : 1396609449,
            "active"    : 1,
            "url"       : "<link>",
            "pos"       : 0,
            "qr"        : "<link>",
            "printPng"  : "<link>",
            "printPdf"  : "<link>"
        },
        "GMW36R" : {
            "code"      : "GMW36R",
            "name"      : "Survey",
            "created"   : 1369661944,
            "active"    : 1,
            "url"       : "<link>",
            "pos"       : 1,
            "qr"        : "",
            "printPng"  : "",
            "printPdf"  : ""
        }
    }
}

Returns a list with all surveys

Response

Data field Description Type
surveys List of all surveys Array
surveys.[code] Dataset per survey Array
surveys.[code].code Survey code String
surveys.[code].name Name of survey String
surveys.[code].created Timestamp of creation Integer
surveys.[code].activated Is the survey active? Integer (0: no; 1: yes)
surveys.[code].url Survey URL String
surveys.[code].pos Is it a Point of Sale survey? Integer (0: no; 1: yes)
surveys.[code].qr Link from QR code image String
surveys.[code].printPng Link to business card template (PNG) String
surveys.[code].printPdf Link to business card template (PDF) String

Point of Sale Umfrage

In a Point of Sale survey, the fields qr, printPng and printPdf are empty.

Invitations

Create and manage personal invitation links to surveys.

invite/url/create

Request

<?php

$data = array(
    'data' => array(
        'code'      => 'FR6JZG',
        'email'     => 'reviewer@example.org',
        'name'      => 'John Doe',
    )
);

Response

{
    "status" : "success",
    "url"    : "<link>",
    "exists" : 0
}

Create a personal invitation link for a survey and return the survey’s URL.

Request

Data field Description Type
code * Survey code String
email * Email address of evaluator String
name Name of evaluator String

Response

Data field Description Type
url Personalized invitation link String
exists Has the email address already been used for the survey? Integer (0: no; 1: yes)

invite/url/get

Request

<?php

$data = array(
    'data' => array(
        'code' => 'FR6JZG'
    )
);

Response

{
    "status"  : "success",
    "invites" : {
        "reviewer1@example.org" : {
            "created" : 1451649600,
            "email"   : "reviewer1@example.org",
            "url"     : "<link>",
            "rated"   : 0,
            "used"    : 0
        },
        "reviewer2@example.org" : {
            "created" : 1451649601,
            "email"   : "reviewer2@example.org",
            "url"     : "<link>",
            "rated"   : 1,
            "used"    : 1451653200
        }
    }
}

Creates a list of all invitation links already created along with their data.

Request

Data field Description Type
code * Survey code String

Response

Datenfeld Beschreibung Typ
invites List of all personalized invitation links Array
invites.[email] Dataset per invitation link Array
invites.[email].created Timestamp of creation Integer
invites.[email].email Email address of evaluator String
invites.[email].url Personalized invitation link String
invites.[email].rated Has an evaluation already been made via this link? Integer (0: no; 1: yes)
invites.[email].used Has the link already been clicked? Integer (0: no, otherwise timestamp)

invite/mail/create

Request

<?php

$data = array(
    'data' => array(
        'code'       => 'FR6JZG',
        'reminder'   => 1,
        'recipients' => array(
            array(
                'email' => 'reviewer1@example.org',
                'name'  => 'John Doe'
            ),
            array(
                'email'              => 'reviewer2@example.org',
                'name'               => 'John Doe',
                'subject'            => 'Your opinion is requested: Give me feedback!',
                'salutation'         => 'Dear Mr. Doe',
                'text'               => 'Thanks for the interesting consultation yesterday. To rate the consulting services, you can use the following link:',
                'reminderSubject'    => 'Reminder: Your opinion is requested: Give me feedback!',
                'reminderSalutation' => 'Dear Mr. Doe',
                'reminderText'       => 'last week we had the consultation. If you want to evaluate the consulting services, you can click the following link:',
            )
        )
    )
);

Response

{
    "status" : "success",
    "mailing"   : {
        "status" : "success",
        "id" : "9959c18c32976a5453e704c0c6b28be5",
        "count" : {
            "all"          : 2,
            "created"      : 2,
            "error"        : 0,
            "ratingExists" : 0,
            "inviteExists" : 0
        },
        "list" : {
            "created" : ["reviewer1@example.org", "reviewer2@example.org"]
        }
    }
}

Creates one or multiple invitations for a survey and sends them as an email. The email subject, title and invitation text can be freely chosen. If these fields are not entered, a standard text is used.

The invitation email will be sent along with the email address for the ProvenExpert profile or via the SMTP server embedded in the profile settings. Emails are not sent in real time, but after a few minutes’ delay.

The invite/mail/status feature can be used to check whether the invitation email has been sent and if there were errors upon sending.

Data protection

Emails may only be sent to customers who have agreed to receive them.

Reminder email

If the invited party does not click on the survey link in the email, a reminder email will be sent after 7 days. This feature is activated as standard.

Request

Data field Description Type Default
code * Survey code String
reminder Sends a reminder email after 7 days Integer (0: no; 1: yes) 1
recipients * Recipient list Array, max. 100 recipients
recipients.[n] Dataset per recipient Array
recipients.[n].email * Email address of recipient String
recipients.[n].name Name of recipient String
recipients.[n].subject Email subject String
recipients.[n].salutation Title in email String
recipients.[n].text Text in email String
recipients.[n].reminderSubject Subject of reminder email String
recipients.[n].reminderSalutation Title in reminder email String
recipients.[n].reminderText Text in reminder email String

Response

Data field Description Type
mailing Personalized invitation link Array
mailing.status Status of mailing String (success; exists; error)
mailing.id ID for mailing, can be used for the feature invite/mail/status String
mailing.count List with number of emails, sorted according to status Array
mailing.count.all Number of all recipients Integer
mailing.count.created Number of invitation emails created Integer
mailing.count.error Number of invitations which could not be created Integer
mailing.count.ratingExists Number of invitations for which a rating already exists Integer
mailing.count.inviteExists Number of invitations for which an invitation already exists Integer
mailing.list List of email addresses, sorted according to status Array
mailing.list.created List of email addresses for which an invitation has been created Array
mailing.list.error List of email addresses for which an invitation could not be created Array
mailing.list.ratingExists List of email addresses for which a rating already exists Array
mailing.list.inviteExists List of email addresses for which an invitation already exists Array

invite/mail/status

Request

<?php

$data = array(
    'data' => array(
        'id' => '9959c18c32976a5453e704c0c6b28be5'
    )
);

Response

{
    "status"  : "success",
    "mailing" : {
        "status"  : "success",
        "created" : 1467127992,
        "count"   : {
            "all"     : 2,
            "send"    : 2,
            "pending" : 0,
            "error"   : 0
        },
        "list"    : {
            "sent" : ["reviewer1@example.org", "reviewer2@example.org"]
        }
    }
}

Returns the sending status for an invitation mailing created with the invite/mail/create function. This includes the number of sent emails, non-sent emails which are in the sending queue and erroneously non-sent emails.

Request

Data field Description Type
id * ID for an invitation mailing String

Response

Datenfeld Beschreibung Typ
mailing Array with status data Array
mailing.status Status of mailing String (success; pending; error)
mailing.created Timestamp of mailing Timestamp
mailing.count List with number of emails, sorted according to status Array
mailing.count.all Number of all emails in the mailing Integer
mailing.count.sent Number of all sent emails in the mailing Integer
mailing.count.pending Number of not yet sent emails in the mailing Integer
mailing.count.error Number of emails which could not be sent Integer
mailing.list List of email addresses, sorted according to status Array
mailing.list.sent List of email addresses used for previously sent invitations Array
mailing.list.pending List of not yet sent email addresses Array
mailing.list.error List of email addresses to which an email could not be sent Array

Rating

rating/summary/get

Request

// no additional data

Response

{
    "status"      : "success",
    "ratingValue" : 4.9,
    "reviewCount" : 167
}

Overall rating and number of ratings for your own profile.

Response

Data field Description Type
ratingValue Overall rating for the profile Float
reviewCount Number of ratings for the profile Integer

rating/summary/children

Request

// no additional data

Response

{
    "status"   : "success",
    "children" : {
        "user1@example.com" : {
            "ratingValue" : 3.8,
            "reviewCount" : 336
        },
        "user2@example.com" : {
            "ratingValue" : 0,
            "reviewCount" : 0
        },
        "user3@example.com" : {
            "ratingValue" : 4.5,
            "reviewCount" : 51
        }
    }
}

Overall rating and number of ratings for profiles from the next Enterprise level down and for all profiles that have been created with this user.

Response

Data field Description Type
children List of all subprofiles Array
children.[email] Dataset per profile Array
children.[email].ratingValue Overall rating for the profile Float
children.[email].reviewCount Number of ratings for the profile Integer

rating/summary/richsnippet

Request

<?php

$data = array(
    'data' => array(
        'version' => 2
    )
);

Response

{
    "status"      : "success",
    "ratingValue" : 4.75,
    "reviewCount" : 16,
    "html"        : "<html>"
}

Create Rich Snippets in HTML code for Google stars.

Request

Data field Description Type Default
version Display modes for stars Integer (1,2,3,4) 1

Display modes for stars

The graphic illustrates the ways in which the stars can be displayed and can be delivered as the parameter version to the API. If the parameter is not set, the first display mode will be selected.

There is a live preview of the display modes on this site: Google Stars

Darstellungsarten der Sterne

Response

Data field Description Type
ratingValue Overall rating for the profile Float
reviewCount Number of ratings for the profile Integer
html HTML code for Rich Snippet String

Authentication

auth/url/get

Request

// no additional data

Response

{
    "status" : "success",
    "url"    : "<link>",
    "expire" : 1452788096
}

Generates a Single Sign On URL which enables you to login to a profile without entering email address and password.

The link is valid for 10 minutes as standard

Response

Data field Description Type
url Link for login String
expire Timestamp representing link expiration date Integer

auth/api/get

Request

// no additional data

Response

{
    "status" : "success",
    "id"     : "d8w4q1C0gU9qr64UEfpjbtcE0DIjfPqL",
    "key"    : "cCJE7FWk6kUQO8CULDhkqDBj1KPhHChKmGWCsMtUDdU"
}

Returns the login details for the ProvenExpert API.

In conjunction with a Proxy User the API login details can be utilized for various profiles.

Response

Data field Description Type
id API ID for authentication String
key API key for authentication String

auth/api/children

Request

// no additional data

Response

{
    "status"   : "success",
    "children" : {
        "firma1@example.com" : {
            "id"  : "t6ohOAHOmfvXIyOGiGdn9qobqnGiOZbY",
            "key" : "6BnXi6cOFBYOPAn4QCx5XagcSvmlUul7wuPjtQKNqdr"
        },
        "firma2@example.com" : {
            "id"  : "BZnVbqdi3HtrzfMKDGVxdvsRa2KNttly",
            "key" : "dBA7f9sQVdvjpSggmJnleZU6jmy6UBhow7Rrk0IXEXq"
        },
        "firma3@example.com" : {
            "id"  : "7khitA9OABIJko5SK1Kdz1as3lIEVVD2",
            "key" : "Bob2TFoZ6wwUmr9CVQY2QYNTR5ueM96zLoxzr1z9WTX"
        }
    }
}

Returns the login details for ProvenExpert API for all subprofiles from the next level down.

Response

Datenfeld Beschreibung Typ
children List of all subprofiles Array
children.[n] Dataset per profile Array
children.[n].id API ID for authentication String
children.[n].key API key for authentication String