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:

FREE & BASIC: Limited functionality

PLUS: API basic functions

PREMIUM: API basic functions & rating endpoint

ENTERPRISE: All API functions

API URL structure

Example API call using 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

Example request-structure using 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

Successful request

{
  "status": "success"
}

Successful 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
  }
}

Included with: ENTERPRISE

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

Data field	Description	Type	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

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	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 (comma-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"
  }
}

Included with: ENTERPRISE

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

Data field	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"
  }
}

Included with: ENTERPRISE

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"
    }
  ]
}

Included with: ENTERPRISE

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
    }
  }
}

Included with: ENTERPRISE

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

Data field	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
    }
  }
}

Included with: ENTERPRISE

Returns the profile settings.

Response

Data field	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>"
}

Included with: ENTERPRISE PREMIUM PLUS BASIC FREE

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
awards	award widgets

Options for the ratings seal vertical

>

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

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

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

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

Options for the 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

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

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

Options for the award widgets

Awards are only visible if the profile owns them already.

Data field	Description	Type	Default
type *	Type of widget	String (awards)
width	Widgets width in pixel	Integer (100 - 300)
fixed	Dock the award widget on brwoser margin	Integer (0: nein; 1: ja)
origin	Distance of widget measured from top or bottom browser margin?	String (top; bottom)
position	Pixel distance of widget from top or bottom browser margin	Integer

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>"
  }
}

Included with: ENTERPRISE

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):

• PNG-images: data:image/png;base64,<Base64-String>
• JPG-images: data:image/jpg;base64,<Base64-String>

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>"
  }
}

Included with: ENTERPRISE

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):

• PNG-images: data:image/png;base64,<Base64-String>
• JPG-images: data:image/jpg;base64,<Base64-String>

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": ""
    }
  }
}

Included with: ENTERPRISE PREMIUM PLUS

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
}

Included with: ENTERPRISE PREMIUM PLUS

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
    }
  }
}

Included with: ENTERPRISE PREMIUM PLUS

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"]
    }
  }
}

Included with: ENTERPRISE PREMIUM PLUS

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"]
    }
  }
}

Included with: ENTERPRISE PREMIUM PLUS

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
}

Included with: ENTERPRISE PREMIUM PLUS BASIC FREE

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
    }
  }
}

Included with: ENTERPRISE

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>"
}

Included with: ENTERPRISE PREMIUM PLUS

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

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
}

Included with: ENTERPRISE

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"
}

Included with: ENTERPRISE

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"
    }
  }
}

Included with: ENTERPRISE

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