ProvenExpert API

Einführung

Mit der ProvenExpert-API können ProvenExpert-Profile erstellt und bearbeitet werden, Umfragen erstellt, Einladungslinks zu Umfragen erstellt, die Gesamtbewertung und Bewertungsanzahl von Profilen abgefragt und den HTML-Code von Bewertungssiegeln erstellt werden.

Um die ProvenExpert-API zu benutzen wird ein ProvenExpert-Profil mit dem jeweiligen Bezahlpaket vorrausgesetzt.

Verfügbare Pakete:

FREE & BASIC: Limitierte Funktionen

PLUS: API-Grundfunktionen

PREMIUM: API-Grundfunktionen & Rating-Endpunkt

ENTERPRISE: Alle API-Funktionen

API-URL Struktur

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 Felder

Die URL setzt sich aus dem API-Endpunkt, der API-Version, dem Service- und Funktionsnamen zusammen.

Feld	Wert
API-Endpunkt	https://www.provenexpert.com/api/
API-Version	v1
Service	auth/url
Funktion	get

Beispiele

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

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

Versionen

Zurzeit steht die API in der Version 1 zur Verfügung.

HTTP Methode

Alle API-Aufrufe müssen als POST gesendet werden.

Datenformat

Die ProvenExpert-API gibt alle Daten als JSON zurück.

Authentifizierung

Die Authentifizierung erfolgt über Basic Auth mittels einer API-ID und eines API-Keys. Diese sind im ProvenExpert-Account hinterlegt.

Request Struktur

Beispielhafte Request-Datenstruktur in PHP

<?php

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

Generell sind alle Felder bei einer API-Anfrage optional. Jedoch müssen je nach verwendeter API-Funktion einige Felder angegeben werden. Alle Pflichtfelder sind in dieser Dokumentation mit einem Sternchen (*) gekennzeichnet.

Datenfeld	Beschreibung	Typ
proxyUser	Stellvertreter User	Array
proxyUser.id	externe UserId (siehe profile/create - externalData.userId)	String
*oder*
proxyUser.email	E-Mail Adresse des Profils	String

limit	Anzahl der zurückgegebenen Datensätze	Integer (max. 100)
offset	Paginierung	Integer
data	Anfragedaten	Array

Stellvertreter User

Wenn ein Stellvertreter User (Parameter proxyUser) angegeben wird, wird der API-Aufruf im Kontext dieses Users ausgeführt. Damit ist es möglich, mit nur einem API-Zugang, viele unterschiedliche Profile zu betreuen.

Rückgabewerte

Erfolgreiche Anfrage

{
  "status": "success"
}

Erfolgreiche Anfrage

Jede Antwort der API enthält das Feld status, das im Erfolgsfall den Wert success enthält. Im Fehlerfall wird error zurückgegeben. Zusätzlich werden in weiteren Feldern, je nach API-Funktion, Daten zurückgegeben.

Einige Funktionen geben zusätzlich das Feld notes zurück. In diesem Array werden Hinweise aufgeführt, die zum Beispiel anzeigen, dass ein unbekanntes Datenfeld angegeben wurde oder ein überlanges Feld gekürzt wurde.

Fehlerhafte Anfrage

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

Fehlerhafte Anfrage

Wenn das Feld status den Wert error hat, wird zusätzlich das Feld errors zurückgegeben. In diesem Array sind ein oder mehrere Fehler enthalten.

Profile

profile/create

Request

<?php

$data = array(
    'data' => array(
        'email'       => 'user@example.com',
        'company'     => 'Firma ABC',
        'description' => 'Firma ABC bietet Dienstleistungen',
        '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": "Firma ABC",
    "description": "Firma ABC bietet Dienstleistungen",
    "openingHours": {
      "days": {
        "weekday1": {
          "start1": "0900",
          "end1": "2200"
        },
        "weekday3": {
          "start1": "0900",
          "end1": "1130",
          "start1": "1200",
          "end1": "1400"
        }
      }
    }
  },
  "login": {
    "url": "<link>",
    "expire": 1452784796
  }
}

Enthalten in: ENTERPRISE

Erstellt ein neues ProvenExpert-Profil.

Es kann entweder ein Firmenprofil oder ein Personenprofil erstellt werden.

Als Rückgabe wird das Profil und eine Single Sign On URL geliefert.

Request

Name	Bescheibung	Typ	Default
email *	E-Mail-Adresse	String

company *	Firmenname (erstellt ein Firmenprofil)	String (mind. 3 Zeichen)
*oder*
firstname *	Vorname (erstellt ein Personenprofil)	String (mind. 2 Zeichen)
lastname *	Nachname (erstellt ein Personenprofil)	String (mind. 2 Zeichen)

password	Passwort (wenn nicht gesetzt wird ein Zufallspasswort gesetzt)	String (mind. 6 Zeichen)
description	Tätigkeitsbeschreibung,	String (max. 80 Zeichen)
about	Profilbeschreibung	String (max. 10.000 Zeichen)
tags	Angebots-Tags (jeweils mit Komma getrennt)	String (max. 600 Zeichen)
avatarUrl	URL zum Profilbild (JPG oder PNG, max. 5 MB)	String
avatarBase64	Profilbild als Data-URL-String (Base64, JPG oder PNG)	String
headerImageUrl	URL zum Profil-Headerbild (JPG oder PNG, max. 5 MB)	String
headerImageBase64	Profil-Headerbild als Data-URL-String (Base64, JPG oder PNG)	String
public	Profil wird öffentlich	Integer (1: ja; 0: nein)	0
imprint	Impressum	String (max. 10.000 Zeichen)

externalData	externe Daten	Array
externalData.userId	fremde UserId (z.B. aus dem CMS des API Nutzers)	String

contact	Kontaktangaben	Array
contact.person	Kontaktperson (wird nur bei Firmenprofil verwendet )	String
contact.company	Firmenname (wird nur bei Personenprofil verwendet)	String
contact.street	Straßenname und Hausnummer	String
contact.zip	Postleitzahl	String
contact.city	Stadt	String
contact.country	Landescode	String (ISO 3166 ALPHA-2)
contact.email	Kontakt-E-Mail-Adresse	String
contact.phone	Telefonnummer	String
contact.mobile	Mobiltelefonnummer	String
contact.fax	Faxnummer	String

websites	Liste mit Webseiten des Profilinhabers	Array (max. 5 Einträge)
websites.[n]	URL und Name der Webseite	Array
websites.[n].label	Name des Links	String
websites.[n].url	URL der Webseite	String

social	Liste mit URLs zu Profilen von sozialen Netzwerken	Array (max. 10 Einträge)
social.[n]	URL des Profils	String

externalRatings	Liste mit URLs zu Profilen bei Bewertungsportalen	Array (max. 100 Einträge)
externalRatings.[n]	URL des Profils (z.B.: yelp, kennstdueinen, ausgezeichnet etc.)	String

openingHours	Öffnungszeiten	Array
openingHours.requestOnly	Termine nur auf Anfrage (mögl. Werte 1: ja; 0: nein) Gilt für ganze Woche, bei 1 werden alle anderen Angaben ignoriert	Integer
openingHours.[n]	Settings für einen einzelnen Tag (mögl. Werte für n : mon, tue, wed, thu, fri, sat, sun). Nicht angegebene Tage werden als ganztägig geschlossen (openDay = ‘off’) gespeichert.	Array
openingHours.[n].start1	1. Anfangszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’. Optional mit Angabe 'pm’, 'am’ : '0930pm’)	String
openingHours.[n].end1	1. Schlusszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’. Optional mit Angabe 'pm’, 'am’ : '0930pm’)	String
openingHours.[n].start2	2. Anfangszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’. Optional mit Angabe 'pm’, 'am’ : '0930pm’)	String
openingHours.[n].end2	2. Schlusszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’. Optional mit Angabe 'pm’, 'am’ : '0930pm’)	String
openingHours.[n].openDay	ganzer Tag geschlossen. (mögl. Werte 'on’, 'off’. Bei 'off’ werden alle anderen Angaben zu dem Tag ignoriert.)	String

Response

Datenfeld	Beschreibung	Typ
profile	Liste mit den Profil Daten	Array
profile.created	Timestamp der Erstellung	Integer
profile.email	E-Mail des Profils	String
profile.profileUrl	URL zum Profil	String
profile.public	Ob das Profil öffentlicht ist	Integer (0: nein; 1: ja)
profile.company	Firmenname (nur beim Firmenprofil)	String
profile.firstname	Vorname (nur beim Personenprofil)	String
profile.lastname	Nachname (nur beim Personenprofil)	String
profile.description	Tätigkeitsbeschreibung	String
login	Daten zum einloggen	Array
login.url	Link zum einloggen	String
login.expire	Timestamp, bis wann der Link gültig ist	Integer
profile.avatarUrl	URL des Avatarbildes	String
profile.imprint	Impressum	String

profile.externalData	externe Daten	Array
profile.externalData.userId	fremde UserId (z.B. aus dem CMS des API Nutzers)	String

profile.tags	Angebots-Tags	String
profile.about	Profilbeschreibung	String
profile.avatarUrl	URL zum Profilbild	String

profile.contact	Kontaktangaben	Array
profile.contact.person	Kontaktperson	String
profile.contact.company	Firmenname	String
profile.contact.street	Straßenname und Hausnummer	String
profile.contact.zip	Postleitzahl	String
profile.contact.city	Stadt	String
profile.contact.country	Landescode	String (ISO 3166 ALPHA-2)
profile.contact.email	Kontakt-E-Mail-Adresse	String
profile.contact.phone	Telefonnummer	String
profile.contact.mobile	Mobiltelefonnummer	String
profile.contact.fax	Faxnummer	String

profile.social	Liste mit URLs zu Profilen von sozialen Netzwerken	Array
profile.social.[n]	URL des Profils	String

profile.openingHours	Öffnungszeiten	Array
profile.openingHours.requestOnly	Termine nur auf Anfrage (mögl. Werte 1: ja; 0: nein) Gilt für ganze Woche	Integer
profile.openingHours.[n]	Settings für einen einzelnen Tag (mögl. Werte für n : mon, tue, wed, thu, fri, sat, sun).	Array
profile.openingHours.[n].start1	1. Anfangszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].end1	1. Schlusszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].start2	2. Anfangszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].end2	2. Schlusszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].openDay	ganzer Tag geschlossen. (mögl. Werte 'on’, 'off’.)	String

Profilbild

Das Profilbild und das Profil-Headerbild können Sie entweder über eine URL oder per Data-URL-String hinzufügen.

Der Data-URL-String muss den folgenden Aufbau haben (siehe Data-URL):

PNG-Bilder: data:image/png;base64,<Base64-String von der Bild-Datei>
JPG-Bilder: data:image/jpg;base64,<Base64-String von der Bild-Datei>

Profil-Headerbild

Das Profil-Headerbild sollte eine Auflösung von 1170 x 216 Pixeln haben damit es in voller Größe auf dem Profil angezeigt wird. Bei einer abweichenden Bildgröße wird ein Ausschnitt von der linken oberen Ecke genommen der über die gesamt Bildbreite geht.

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' => '0930pm',
                'end1' => '1100pm',
            ),
            '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": "Firma ABC",
    "openingHours": {
      "days": {
        "weekday1": {
          "start1": "0930",
          "end1": "1200"
        },
        "weekday6": {
          "start1": "0930pm",
          "end1": "1100pm"
        },
        "weekday7": {
          "start1": "0930",
          "end1": "1100"
        }
      }
    }
  }
}

Enthalten in: ENTERPRISE

Bearbeitet ein bestehendes ProvenExpert-Profil.

Nur die zu verändernden Felder müssen angegeben werden. Zum Löschen eines Feldes muss ein Leerstring angegeben werden. Arrays mit numerischen Indizes können nur als Ganzes bearbeitet werden (z.B.: websites, social), wohingegen die Felder von assoziativen Arrays (z.B.: contact) einzeln bearbeitet werden können.

Als Rückgabe wird das bearbeitete Profil geliefert.

Request

Name	Bescheibung	Typ
email	E-Mail-Adresse	String
password	Passwort	String (mind. 6 Zeichen)
description	Tätigkeitsbeschreibung,	String (max. 80 Zeichen)
about	Profilbeschreibung	String (max. 10.000 Zeichen)
tags	Angebots-Tags (jeweils mit Komma getrennt)	String (max. 600 Zeichen)
avatarUrl	URL zum Profilbild (JPG oder PNG, max. 5 MB)	String
avatarBase64	Profilbild als Data-URL-String (Base64, JPG oder PNG)	String
headerImageUrl	URL zum Profil-Headerbild (JPG oder PNG, max. 5 MB)	String
headerImageBase64	Profil-Headerbild als Data-URL-String (Base64, JPG oder PNG)	String
public	Profil wird öffentlich	Integer (1: ja; 0: nein)
imprint	Impressum	String (max. 10.000 Zeichen)

externalData	externe Daten	Array
externalData.userId	fremde UserId (z.B. aus dem CMS des API Nutzers)	String

contact	Kontaktangaben	Array
contact.person	Kontaktperson (wird nur bei Firmenprofil verwendet )	String
contact.company	Firmenname (wird nur bei Personenprofil verwendet)	String
contact.street	Straßenname und Hausnummer	String
contact.zip	Postleitzahl	String
contact.city	Stadt	String
contact.country	Landescode	String (ISO 3166 ALPHA-2)
contact.email	Kontakt-E-Mail-Adresse	String
contact.phone	Telefonnummer	String
contact.mobile	Mobiltelefonnummer	String
contact.fax	Faxnummer	String

websites	Liste mit Webseiten des Profilinhabers	Array (max. 5 Einträge)
websites.[n]	URL und Name der Webseite	Array
websites.[n].label	Name des Links	String
websites.[n].url	URL der Webseite	String

social	Liste mit URLs zu Profilen von sozialen Netzwerken	Array (max. 10 Einträge)
social.[n]	URL des Profils	String

externalRatings	Liste mit URLs zu Profilen bei Bewertungsportalen	Array (max. 100 Einträge)
externalRatings.[n]	URL des Profils (z.B.: yelp, kennstdueinen, ausgezeichnet etc.)	String

openingHours	Öffnungszeiten	Array
openingHours.requestOnly	Termine nur auf Anfrage (mögl. Werte 1: ja; 0: nein) Gilt für ganze Woche, bei 1 werden alle anderen Angaben ignoriert	Integer
openingHours.[n]	Settings für einen einzelnen Tag (mögl. Werte für n : mon, tue, wed, thu, fri, sat, sun). Nicht angegebene Tage werden als ganztägig geschlossen (openDay = ‘off’) gespeichert.	Array
openingHours.[n].start1	1. Anfangszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’. Optional mit Angabe 'pm’, 'am’ : '0930pm’)	String
openingHours.[n].end1	1. Schlusszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’. Optional mit Angabe 'pm’, 'am’ : '0930pm’)	String
openingHours.[n].start2	2. Anfangszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’. Optional mit Angabe 'pm’, 'am’ : '0930pm’)	String
openingHours.[n].end2	2. Schlusszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’. Optional mit Angabe 'pm’, 'am’ : '0930pm’)	String
openingHours.[n].openDay	ganzer Tag geschlossen. (mögl. Werte 'on’, 'off’. Bei 'off’ werden alle anderen Angaben zu dem Tag ignoriert.)	String

Response

Datenfeld	Beschreibung	Typ
profile	Liste mit den Profil Daten	Array
profile.created	Timestamp der Erstellung	Integer
profile.email	E-Mail des Profils	String
profile.profileUrl	URL zum Profil	String
profile.public	Ob das Profil öffentlicht ist	Integer (0: nein; 1: ja)
profile.company	Firmenname (nur beim Firmenprofil)	String
profile.firstname	Vorname (nur beim Personenprofil)	String
profile.lastname	Nachname (nur beim Personenprofil)	String
profile.description	Tätigkeitsbeschreibung	String
profile.avatarUrl	URL des Avatarbildes	String
profile.imprint	Impressum	String

profile.externalData	externe Daten	Array
profile.externalData.userId	fremde UserId (z.B. aus dem CMS des API Nutzers)	String

profile.tags	Angebots-Tags	String
profile.about	Profilbeschreibung	String
profile.avatarUrl	URL zum Profilbild	String

profile.contact	Kontaktangaben	Array
profile.contact.person	Kontaktperson	String
profile.contact.company	Firmenname	String
profile.contact.street	Straßenname und Hausnummer	String
profile.contact.zip	Postleitzahl	String
profile.contact.city	Stadt	String
profile.contact.country	Landescode	String (ISO 3166 ALPHA-2)
profile.contact.email	Kontakt-E-Mail-Adresse	String
profile.contact.phone	Telefonnummer	String
profile.contact.mobile	Mobiltelefonnummer	String
profile.contact.fax	Faxnummer	String

profile.social	Liste mit URLs zu Profilen von sozialen Netzwerken	Array
profile.social.[n]	URL des Profils	String

profile.openingHours	Öffnungszeiten	Array
profile.openingHours.requestOnly	Termine nur auf Anfrage (mögl. Werte 1: ja; 0: nein) Gilt für ganze Woche	Integer
profile.openingHours.[n]	Settings für einen einzelnen Tag (mögl. Werte für n : mon, tue, wed, thu, fri, sat, sun).	Array
profile.openingHours.[n].start1	1. Anfangszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].end1	1. Schlusszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].start2	2. Anfangszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].end2	2. Schlusszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].openDay	ganzer Tag geschlossen. (mögl. Werte 'on’, 'off’.)	String

Profilbild

Das Profilbild und das Profil-Headerbild können Sie entweder über eine URL oder per Data-URL-String hinzufügen.

Der Data-URL-String muss den folgenden Aufbau haben (siehe Data-URL):

PNG-Bilder: data:image/png;base64,<Base64-String von der Bild-Datei>
JPG-Bilder: data:image/jpg;base64,<Base64-String von der Bild-Datei>

Profil-Headerbild

Um das aktuelle Headerbild ersatzlos zu löschen, muss als Wert von headerImageUrl oder headerImageBase64 ein Leerstring gesendet werden.

profile/get

Request

// keine zusätzlichen Daten

Response

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

Enthalten in: ENTERPRISE

Gibt das eigene Profil zurück.

Response

Datenfeld	Beschreibung	Typ
profile	Liste mit den Profil Daten	Array
profile.created	Timestamp der Erstellung	Integer
profile.email	E-Mail des Profils	String
profile.profileUrl	URL zum Profil	String
profile.public	Ob das Profil öffentlicht ist	Integer (0: nein; 1: ja)
profile.company	Firmenname (nur beim Firmenprofil)	String
profile.firstname	Vorname (nur beim Personenprofil)	String
profile.lastname	Nachname (nur beim Personenprofil)	String
profile.description	Tätigkeitsbeschreibung	String
profile.avatarUrl	URL des Avatarbildes	String
profile.imprint	Impressum	String

profile.externalData	externe Daten	Array
profile.externalData.userId	fremde UserId (z.B. aus dem CMS des API Nutzers)	String

profile.tags	Angebots-Tags	String
profile.about	Profilbeschreibung	String
profile.avatarUrl	URL zum Profilbild	String

profile.contact	Kontaktangaben	Array
profile.contact.person	Kontaktperson	String
profile.contact.company	Firmenname	String
profile.contact.street	Straßenname und Hausnummer	String
profile.contact.zip	Postleitzahl	String
profile.contact.city	Stadt	String
profile.contact.country	Landescode	String (ISO 3166 ALPHA-2)
profile.contact.email	Kontakt-E-Mail-Adresse	String
profile.contact.phone	Telefonnummer	String
profile.contact.mobile	Mobiltelefonnummer	String
profile.contact.fax	Faxnummer	String

profile.social	Liste mit URLs zu Profilen von sozialen Netzwerken	Array
profile.social.[n]	URL des Profils	String

profile.openingHours	Öffnungszeiten	Array
profile.openingHours.requestOnly	Termine nur auf Anfrage (mögl. Werte 1: ja; 0: nein) Gilt für ganze Woche	Integer
profile.openingHours.[n]	Settings für einen einzelnen Tag (mögl. Werte für n : mon, tue, wed, thu, fri, sat, sun).	Array
profile.openingHours.[n].start1	1. Anfangszeit (mögl. Werte ‘0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].end1	1. Schlusszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].start2	2. Anfangszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].end2	2. Schlusszeit (mögl. Werte '0000’, '0030’, '0100’, '0130’ … '2400’.	String
profile.openingHours.[n].openDay	ganzer Tag geschlossen. (mögl. Werte 'on’, 'off’.)	String

profile/children

Request

// keine zusätzlichen Daten

Response

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

Enthalten in: ENTERPRISE

Gibt bei einem Enterprise Profil alle untergeordneten Profile der nächstunteren Ebene zurück. Bei einem normalen Profil werden alle Profile zurückgegeben die mit diesem Profil erstellt wurden.

Response

Datenfeld	Beschreibung	Typ
profiles	Liste mit allen Profilen	Array
profiles.[n]	Datensatz für ein Profil	Array
profiles.[n].created	Timestamp der Erstellung	Integer
profiles.[n].email	E-Mail des Profils	String
profiles.[n].profileUrl	URL zum Profil	String
profiles.[n].public	Ob das Profil öffentlicht ist	Integer (0: nein; 1: ja)
profiles.[n].company	Firmenname (nur beim Firmenprofil)	String
profiles.[n].firstname	Vorname (nur beim Personenprofil)	String
profiles.[n].lastname	Nachname (nur beim Personenprofil)	String
profiles.[n].description	Tätigkeitsbeschreibung	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
    }
  }
}

Enthalten in: ENTERPRISE

Bearbeitet die Profileinstellungen.

Es müssen nur die Werte angegeben werden, die verändert werden sollen, alle anderen Einstellungen bleiben unverändert.

Als Rückgabe werden alle aktuellen Profileinstellungen geliefert.

Response

Name	Bescheibung	Typ
public	Ob das Profil öffentlicht ist	Integer (0: nein; 1: ja)

privacy	Liste der Privatsphäre-Einstellungen	Array
privacy.ratingButton	Profilbesucher können mich bewerten	Integer (0: nein; 1: ja)
privacy.ratingButtonWithCode	Bewertung nur nach meiner Freigabe ermöglichen	Integer (0: nein; 1: ja)
privacy.showVoterData	Informationen zu Bewertern anzeigen	Integer (0: nein; 1: ja)
privacy.showCompanyName	Firmennamen anzeigen	Integer (0: nein; 1: ja)
privacy.showName	Vor- und Nachnamen anzeigen	Integer (0: nein; 1: ja)
privacy.showLastname	Nachnamen vollständig anzeigen	Integer (0: nein; 1: ja)
privacy.contactButton	Besucher können mir Nachrichten schreiben	Integer (0: nein; 1: ja)
privacy.showTopCompetences	Meine Top-Kompetenzen anzeigen	Integer (0: nein; 1: ja)
privacy.showAllCompetences	Alle bewerteten Kompetenzen anzeigen	Integer (0: nein; 1: ja)
privacy.showRatingCompetences	Kompetenzen bei Klick auf Kategorien anzeigen	Integer (0: nein; 1: ja)
privacy.showExternalRatings	Meine Bewertungen aus anderen Quellen anzeigen	Integer (0: nein; 1: ja)

notify	Liste der Benachrichtigungs-Einstellungen	Array
notify.rating	Neue Bewertungen auf ProvenExpert.com	Integer (0: nein; 1: ja)
notify.ratingRequest	Anfragen zur Bewertung	Integer (0: nein; 1: ja)
notify.contactRequest	Kontaktanfragen	Integer (0: nein; 1: ja)
notify.service	Service-Infos von ProvenExpert	Integer (0: nein; 1: ja)
notify.externalRating	Neue Bewertungen aus anderen Quellen	Integer (0: nein; 1: ja)

mails	Liste mit weiteren E-Mail Einstellungen	Array
mails.reporting	Aktuelle Statusinformationen und Tipps zu meinem ProvenExpert-Profil (Reporting)	Integer (0: nein; 1: ja)
mails.newsletter	Interessante Produktfunktionen, Neuigkeiten und Sonderaktionen von ProvenExpert (Newsletter)	Integer (0: nein; 1: ja)

profile/settings/get

Request

// keine zusätzlichen Daten

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

Enthalten in: ENTERPRISE

Gibt die Profil-Einstellungen zurück.

Response

Name	Bescheibung	Typ
public	Ob das Profil öffentlicht ist	Integer (0: nein; 1: ja)

privacy	Liste der Privatsphäre-Einstellungen	Array
privacy.ratingButton	Profilbesucher können mich bewerten	Integer (0: nein; 1: ja)
privacy.ratingButtonWithCode	Bewertung nur nach meiner Freigabe ermöglichen	Integer (0: nein; 1: ja)
privacy.showVoterData	Informationen zu Bewertern anzeigen	Integer (0: nein; 1: ja)
privacy.showCompanyName	Firmennamen anzeigen	Integer (0: nein; 1: ja)
privacy.showName	Vor- und Nachnamen anzeigen	Integer (0: nein; 1: ja)
privacy.showLastname	Nachnamen vollständig anzeigen	Integer (0: nein; 1: ja)
privacy.contactButton	Besucher können mir Nachrichten schreiben	Integer (0: nein; 1: ja)
privacy.showTopCompetences	Meine Top-Kompetenzen anzeigen	Integer (0: nein; 1: ja)
privacy.showAllCompetences	Alle bewerteten Kompetenzen anzeigen	Integer (0: nein; 1: ja)
privacy.showRatingCompetences	Kompetenzen bei Klick auf Kategorien anzeigen	Integer (0: nein; 1: ja)
privacy.showExternalRatings	Meine Bewertungen aus anderen Quellen anzeigen	Integer (0: nein; 1: ja)

notify	Liste der Benachrichtigungs-Einstellungen	Array
notify.rating	Neue Bewertungen auf ProvenExpert.com	Integer (0: nein; 1: ja)
notify.ratingRequest	Anfragen zur Bewertung	Integer (0: nein; 1: ja)
notify.contactRequest	Kontaktanfragen	Integer (0: nein; 1: ja)
notify.service	Service-Infos von ProvenExpert	Integer (0: nein; 1: ja)
notify.externalRating	Neue Bewertungen aus anderen Quellen	Integer (0: nein; 1: ja)

mails	Liste mit weiteren E-Mail Einstellungen	Array
mails.reporting	Aktuelle Statusinformationen und Tipps zu meinem ProvenExpert-Profil (Reporting)	Integer (0: nein; 1: ja)
mails.newsletter	Interessante Produktfunktionen, Neuigkeiten und Sonderaktionen von ProvenExpert (Newsletter)	Integer (0: nein; 1: ja)

profile/delete

Request

// keine zusätzlichen Daten

Response

{
  "status": "success"
}

Enthalten in: ENTERPRISE

Löscht ein Profil und alle dazugehörigen Daten wie Bewertungen und Umfragen.

Es ist nur möglich das Profil eines Stellvertreter Users zu löschen. Das eigene Profil kann nicht gelöscht werden.

Handelt es sich beim zu löschendem Profil um ein Enterprise Profil, das noch untergeordnete Profile enthält, so ist ein löschen nicht möglich.

Es können nur Profile gelöscht werden die auch über die API erstellt wurden.

Request

<?php

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

Response

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

Enthalten in: ENTERPRISE PREMIUM PLUS BASIC FREE

Erstellt ein neues Bewertungssiegel. Es wird der HTML Code des Siegels zurückgeliefert.

Request

Folgende Typen gibt es:

Type	Beschreibung
portrait	Bewertungssiegel hochkant
square	Bewertungssiegel quadratisch
landscape	Bewertungssiegel quer
circle	Qualitätssiegel
logo	ProvenExpert-Logo
bar	Bewertungssiegel am unteren Browser-Rand
landing	Bewertungs-Widget
awards	Award-Widgets

Optionen für das Bewertungssiegel hochkant

>

Datenfeld	Beschreibung	Typ	Default
type *	Art des Widgets	String (portrait)
width *	Breite des Siegels in Pixel	Integer (90 - 250)
feedback	Kundenstimme anzeigen	Integer (0: nein; 1: ja)	0
slider	Bewertungssiegel als Slider am Browserrand anzeigen	Integer (0: nein; 1: ja)
fixed	Siegel am Browserrand andocken	Integer (0: nein; 1: ja)
origin	Ob der Abstand des Siegels vom oberen oder unteren Browserrand gemessen wird	String (top; bottom)
position	Pixelabstand des Siegels vom oberen bzw. unteren Browserrand	Integer
side	Browserseite an der das Bewertungssiegel angedockt wird	String (left; right)
viewport	Browserbreite in Pixel ab dem das Siegel angezeigt wird	Integer

Optionen für das Bewertungssiegel quadratisch

Datenfeld	Beschreibung	Typ	Default
type *	Art des Widgets	String (square)
width *	Breite des Siegels in Pixel	Integer (90 - 300)
feedback	Kundenstimme anzeigen	Integer (0: nein; 1: ja)	0
slider	Bewertungssiegel als Slider am Browserrand anzeigen	Integer (0: nein; 1: ja)
fixed	Siegel am Browserrand andocken	Integer (0: nein; 1: ja)
origin	Ob der Abstand des Siegels vom oberen oder unteren Browserrand gemessen wird	String (top; bottom)
position	Pixelabstand des Siegels vom oberen bzw. unteren Browserrand	Integer
side	Browserseite an der das Bewertungssiegel angedockt wird	String (left; right)
viewport	Browserbreite in Pixel ab dem das Siegel angezeigt wird	Integer

Optionen für das Bewertungssiegel quer

Datenfeld	Beschreibung	Typ	Default
type *	Art des Widgets	String (landscape)
width *	Breite des Siegels in Pixel	Integer (110 - 300)
feedback	Kundenstimme anzeigen	Integer (0: nein; 1: ja)	0
slider	Bewertungssiegel als Slider am Browserrand anzeigen	Integer (0: nein; 1: ja)
fixed	Siegel am Browserrand andocken	Integer (0: nein; 1: ja)
origin	Ob der Abstand des Siegels vom oberen oder unteren Browserrand gemessen wird	String (top; bottom)
position	Pixelabstand des Siegels vom oberen bzw. unteren Browserrand	Integer
side	Browserseite an der das Bewertungssiegel angedockt wird	String (left; right)
viewport	Browserbreite in Pixel ab dem das Siegel angezeigt wird	Integer

Optionen für das Qualitätssiegel

Datenfeld	Beschreibung	Typ
type *	Art des Widgets	String (circle)
width *	Breite des Siegels in Pixel	Integer (60 - 300)
fixed	Qualitätssiegel am Browserrand andocken	Integer (0: nein; 1: ja)
origin	Ob der Abstand des Siegels vom oberen oder unteren Browserrand gemessen wird	String (top; bottom)
position	Pixelabstand des Siegels vom oberen bzw. unteren Browserrand	Integer
side	Browserseite an der das Bewertungssiegel angedockt wird	String (left; right)
viewport	Browserbreite in Pixel ab dem das Siegel angezeigt wird	Integer

Optionen für das ProvenExpert-Logo

Datenfeld	Beschreibung	Typ	Default
type *	Art des Widgets	String (logo)
width *	Breite des Siegels in Pixel	Integer (100 - 300)
style	Farbe des Logos	String (black;white)	black
fixed	ProvenExpert-Logo am Browserrand andocken	Integer (0: nein; 1: ja)
origin	Ob der Abstand des Siegels vom oberen oder unteren Browserrand gemessen wird	String (top; bottom)
position	Pixelabstand des Siegels vom oberen bzw. unteren Browserrand	Integer
side	Browserseite an der das Bewertungssiegel angedockt wird	String (left; right)
viewport	Browserbreite in Pixel ab dem das Siegel angezeigt wird	Integer

Optionen für das Bewertungssiegel am unteren Browser-Rand

Datenfeld	Beschreibung	Typ	Default
type *	Art des Widgets	String (bar)
style	Hintergrundfarbe	String (black;white)	white
feedback	Kundenstimme anzeigen	Integer (0: nein; 1: ja)	0

Datenfeld	Beschreibung	Typ	Default
type *	Art des Widgets	String (landing)
style	Farbe der Headerzeile	String (black;white)	black
avatar	Porträtbild anzeigen	Integer (0: nein; 1: ja)	1
feedback	Kundenstimme anzeigen	Integer (0: nein; 1: ja)	1
competence	Top-Kompetenzen anzeigen	Integer (0: nein; 1: ja)	1

Optionen für die Award-Widgets

Awards sind nur sichbar wenn das Profil diese bereits erworben hat.

Datenfeld	Beschreibung	Typ
type *	Art des Widgets	String (awards)
width	Breite des Widgets in Pixel	Integer (100 - 300)
fixed	Award Widget am Browserrand andocken	Integer (0: nein; 1: ja)
origin	Ob der Abstand des Widgets vom oberen oder unteren Browserrand gemessen wird	String (top; bottom)
position	Pixelabstand des Widgets vom oberen bzw. unteren Browserrand	Integer

Response

Datenfeld	Beschreibung	Typ
html	HTML-Code des Bewertungssiegels	String

Umfragen

survey/create

Request

<?php

$data = array(
    // ...
    'data' => array(
        'name'          => 'Neue Umfrage',
        'pos'           => 1,
        'posLabel'      => 'Filiale 5',
        'posLogoBase64' => 'data:image/png;base64,iVBORw0...'
    )
);

// or

$data = array(
    // ...
    'data' => array(
        'name'     => 'Neue Umfrage',
        'pos'      => 0
    )
);

Response

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

Enthalten in: ENTERPRISE

Erstellt eine neue Umfrage.

Request

Datenfeld	Beschreibung	Typ	Default
name *	Name der Umfrage	String
pos	Ob es eine Point of Sale Umfrage ist	Integer (0: nein; 1: ja)	0
posLabel	Label für das POS Template	String
posLogoUrl	URL zum POS Logo (JPG oder PNG, max. 5 MB)	String
posLogoBase64	Das Logo als Data-URL-String (Base64)	String

Response

Datenfeld	Beschreibung	Typ
survey	Datensatz von der Umfrage	Array
survey.code	Umfragen-Code	String
survey.name	Name der Umfrage	String
survey.created	Timestamp der Erstellung	Integer
survey.activated	Ob die Umfrage aktiv ist	Integer (0: nein; 1: ja)
survey.url	URL der Umfrage	String
survey.pos	Ob es eine Point of Sale Umfrage ist	Integer (0: nein; 1: ja)
survey.qr	Link vom QR-Code Bild	String
survey.printPng	Link zur Visitenkartenvorlage (PNG)	String
survey.printPdf	Link zur Visitenkartenvorlage (PDF)	String

Point of Sale Umfrage (POS)

Zur Erstellung von Point of Sale Umfragen wird eine Einstellung im Benutzer Account benötigt. Dies kann nur durch den ProvenExpert-Support erfolgen. Bei einer Point of Sale Umfrage, sind die Felder qr, printPng und printPdf leer.

Das Logo für die POS Umfrage können Sie entweder über eine URL oder per Data-URL-String hinzufügen.

Der Data-URL-String muss den folgenden Aufbau haben (siehe Data-URL):

PNG-Bilder: data:image/png;base64,<Base64-String von der Bild-Datei>
JPG-Bilder: data:image/jpg;base64,<Base64-String von der Bild-Datei>

survey/update

Request

<?php

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

Response

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

Enthalten in: ENTERPRISE

Aktualisiert eine Umfrage.

Request

Filterfeld	Beschreibung	Typ
code *	Umfrage-Code der zu ändernden Umfrage	String

Datenfeld	Beschreibung	Typ
active	De/Aktiviert die Umfrage	Integer (0: nein; 1: ja)
posLabel	Label für das POS Template	String
posLogoUrl	URL zum POS Logo (JPG oder PNG, max. 5 MB)	String
posLogoBase64	Das Logo als Data-URL-String (Base64)	String

Response

Datenfeld	Beschreibung	Typ
survey	Datensatz von der Umfrage	Array
survey.code	Umfragen-Code	String
survey.name	Name der Umfrage	String
survey.created	Timestamp der Erstellung	Integer
survey.activated	Ob die Umfrage aktiv ist	Integer (0: nein; 1: ja)
survey.url	URL der Umfrage	String
survey.pos	Ob es eine Point of Sale Umfrage ist	Integer (0: nein; 1: ja)
survey.qr	Link vom QR-Code Bild	String
survey.printPng	Link zur Visitenkartenvorlage (PNG)	String
survey.printPdf	Link zur Visitenkartenvorlage (PDF)	String

Point of Sale Umfrage

Bei einer Point of Sale Umfrage, sind die Felder qr, printPng und printPdf leer.

Das Logo für die POS Umfrage können Sie entweder über eine URL oder per Data-URL-String hinzufügen.

Der Data-URL-String muss den folgenden Aufbau haben (siehe Data-URL):

PNG-Bilder: data:image/png;base64,<Base64-String von der Bild-Datei>
JPG-Bilder: data:image/jpg;base64,<Base64-String von der Bild-Datei>

survey/get

Request

// keine zusätzlichen Daten

Response

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

Enthalten in: ENTERPRISE PREMIUM PLUS

Gibt eine Liste aller Umfragen zurück

Response

Datenfeld	Beschreibung	Typ
surveys	Liste aller Umfragen	Array
surveys.[code]	Datensatz pro Umfrage	Array
surveys.[code].code	Umfragen-Code	String
surveys.[code].name	Name der Umfrage	String
surveys.[code].created	Timestamp der Erstellung	Integer
surveys.[code].activated	Ob die Umfrage aktiv ist	Integer (0: nein; 1: ja)
surveys.[code].url	URL der Umfrage	String
surveys.[code].pos	Ob es eine Point of Sale Umfrage ist	Integer (0: nein; 1: ja)
surveys.[code].qr	Link vom QR-Code Bild	String
surveys.[code].printPng	Link zur Visitenkartenvorlage (PNG)	String
surveys.[code].printPdf	Link zur Visitenkartenvorlage (PDF)	String

Point of Sale Umfrage

Bei einer Point of Sale Umfrage, sind die Felder qr, printPng und printPdf leer.

Einladungen

Persönliche Einladungslinks zu Umfragen erstellen und verwalten.

invite/url/create

Request

<?php

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

Response

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

Enthalten in: ENTERPRISE PREMIUM PLUS

Einen persönlichen Einladungslink für eine Umfrage erstellen und dessen URL zurückgeben.

Request

Datenfeld	Beschreibung	Typ
code *	Umfrage-Code	String
email *	E-Mail Adresse vom Bewerter	String
name	Name vom Bewerter	String

Response

Datenfeld	Beschreibung	Typ
url	Personalisierter Einladungslink	String
exists	Ob die E-Mail Adresse für die Umfrage schon benutzt wurde	Integer (0: nein; 1: ja)

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

Enthalten in: ENTERPRISE PREMIUM PLUS

Liste aller bisher erstellten Einladungslinks mit den dazugezuhörigen Daten erstellen.

Request

Datenfeld	Beschreibung	Typ
code *	Umfrage-Code	String

Response

Datenfeld	Beschreibung	Typ
invites	Liste aller personalisierten Einladungslinks	Array
invites.[email]	Datensatz pro Einladungslink	Array
invites.[email].created	Timestamp der Erstellung	Integer
invites.[email].email	E-Mail Adresse vom Bewerter	String
invites.[email].url	Personalisierter Einladungslink	String
invites.[email].rated	Ob über den Link schon bewertet wurde	Integer (0: nein; 1: ja)
invites.[email].used	Ob der Link bereits angeklickt wurde	Integer (0: nein, sonst 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'               => 'Max Mustermann',
                'subject'            => 'Ihre Meinung ist gefragt: Geben Sie mir Feedback!',
                'salutation'         => 'Sehr geehrter Herr Mustermann',
                'text'               => 'vielen Dank für das interessante Beratungsgespräch gestern. Die Bewertung für die Beratungsleistung können Sie über folgenden Link abgeben:',
                'reminderSubject'    => 'Erinnerung: Ihre Meinung ist gefragt: Geben Sie mir Feedback!',
                'reminderSalutation' => 'Hallo Herr Mustermann',
                'reminderText'       => 'letzte Woche hatten wir das Beratungsgespräch. Wenn Sie die Beratungsleistung bewerten möchten, können Sie den folgenden Link anklicken:',
            )
        )
    )
);

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

Enthalten in: ENTERPRISE PREMIUM PLUS

Erstellt eine oder mehrere Einladungen für eine Umfrage und versendet sie als E-Mail. Der E-Mail Betreff, die Anrede und der Einladungstext können frei gewählt werden. Werden diese Felder nicht angegeben, wird ein Standardtext verwendet.

Die Einladungs E-Mails werden mit der E-Mail Adresse des ProvenExpert Profils versendet, bzw. über den in den Profil-Einstellungen hinterlegten SMTP-Server. Die Versendung der E-Mails wird nicht in Echtzeit vorgenommen, sondern geschieht zeitlich um wenige Minuten verzögert.

Im Einladungstext kann nur reiner Text zu benutzt werden. Bei Benutzung von HTML-Elementen wird ein Fehler zurückgegeben. Mit Zeilenumbrüchen (Whitespace: “\n”) können Sie bei längeren Text Absätze manuell hinzufügen.

Um zu ermitteln ob die Einladungs E-Mail versendet wurden und ob es eventuell Fehler beim Versand gab, kann die Funktion invite/mail/status verwendet werden.

Datenschutz

Es dürfen nur Kunden angeschrieben werden, die ihre Einwilligung zum Erhalt von E-Mails gegeben haben.

Erinnerungs E-Mail

Wenn der Eingeladene nicht auf den Umfragelink in der E-Mail klickt, wird nach 7 Tagen eine Erinnerungs E-Mail versendet. Dieses Feature ist standardmäßig aktiviert.

Request

Datenfeld	Beschreibung	Typ	Default
code *	Umfrage-Code	String
reminder	Versendet eine Erinnerungs E-Mail nach 7 Tagen	Integer (0: nein; 1: ja)	1
recipients *	Empfängerliste	Array, max. 100 Empfänger
recipients.[n]	Datensatz pro Empfänger	Array
recipients.[n].email *	E-Mail Adresse vom Empfänger	String
recipients.[n].name	Name vom Empfänger	String
recipients.[n].subject	Betreff der E-Mail	String
recipients.[n].salutation	Anrede in der E-Mail	String
recipients.[n].text	Text in der E-Mail	String
recipients.[n].reminderSubject	Betreff der Erinnerungs E-Mail	String
recipients.[n].reminderSalutation	Anrede in der Erinnerungs E-Mail	String
recipients.[n].reminderText	Text in der Erinnerungs E-Mail	String

Response

Datenfeld	Beschreibung	Typ
mailing	Personalisierter Einladungslink	Array
mailing.status	Status des Mailings	String (success; exists; error)
mailing.id	ID des Mailings, kann für die Funktion invite/mail/status verwendet werden	String
mailing.count	Liste mit Anzahl der E-Mails, nach Status sortiert	Array
mailing.count.all	Anzahl aller Empfänger	Integer
mailing.count.created	Anzahl der erstellten Einladungs E-Mails	Integer
mailing.count.error	Anzahl der Einladungen die nicht erstellt werden konnten	Integer
mailing.count.ratingExists	Anzahl der Einladungen zu denen bereits eine Bewertung existiert	Integer
mailing.count.inviteExists	Anzahl der Einladungen zu denen bereits eine Einladung existiert	Integer
mailing.list	Listen von E-Mail Adressen, nach Status sortiert	Array
mailing.list.created	Liste der E-Mail Adressen zu denen eine Einladung erstellt wurde	Array
mailing.list.error	Liste der E-Mail Adressen zu denen keine Einladung erstellt werden konnte	Array
mailing.list.ratingExists	Liste der E-Mail Adressen zu denen bereits eine Bewertung existiert	Array
mailing.list.inviteExists	Liste der E-Mail Adressen zu denen bereits eine Einladung existiert	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"]
    }
  }
}

Enthalten in: ENTERPRISE PREMIUM PLUS

Gibt den Versandtstatus eines Einladungs-Mailings, das mit der Funktion invite/mail/create erstellt wurde, zurück. Darin enthalten sind die Anzahl an versendeten E-Mails, nicht versendete E-Mails, die sich noch in der Warteschlange befinden und fehlerhafte unversendete E-Mails.

Request

Datenfeld	Beschreibung	Typ
id *	ID eines Einladungs Mailings	String

Response

Datenfeld	Beschreibung	Typ
mailing	Array mit Statusdaten	Array
mailing.status	Status des Mailings	String (success; pending; error)
mailing.created	Erstellungszeit des Mailings	Timestamp
mailing.count	Liste mit Anzahl der E-Mails, nach Status sortiert	Array
mailing.count.all	Anzahl aller E-Mail des Mailings	Integer
mailing.count.sent	Anzahl der versendeten E-Mails des Mailings	Integer
mailing.count.pending	Anzahl der noch nicht versendeten E-Mails des Mailings	Integer
mailing.count.error	Anzahl der E-Mails die nicht versendet werden konnten	Integer
mailing.list	Listen von E-Mail Adressen, nach Status sortiert	Array
mailing.list.sent	Liste von E-Mail Adressen der bisher versendeten Einladungen	Array
mailing.list.pending	Liste der noch nicht versendeten E-Mail Adressen	Array
mailing.list.error	Liste von E-Mail Adressen an die keine E-Mail versendet werden konnte	Array

Rating

rating/get

Request

<?php

$data = array(
    'filter' => array(
        'status'           => 'published',
        'ratingValueAbove' => 4
    )
);

Response

{
  "status": "success",
  "ratings": {
    "1pQAlNUB3RGZiWapkxGZ2Dmo2HwZ5VGZ": {
      "created": 1484574525,
      "ratingValue": 4.66,
      "status": "published",
      "recommendation": 1,
      "topicCode": "SURV12",
      "user": {
        "name": "Max Mustermann"
      },
      "feedback": "Sehr gutes Seminar.",
      "ratings": {
        "category_0": 5,
        "category_1": 4,
        "category_2": 5
      },
      "ratingDetails": {
        "category_0": {
          "question_1": 5
        }
      },
      "labels": {
        "category_0": "Qualität",
        "category_0-question_1": "Fachkenntnisse",
        "category_1": "Nutzen",
        "category_2": "Leistungen"
      }
    }
  }
}

Enthalten in: ENTERPRISE PREMIUM

Ruft Bewertungen eines einzelnen Profils ab.

Request

Filterfeld	Beschreibung	Typ
id	ID der Bewertung	String
status	nur Bewertungen mit diesem Veröffentlichungsstatus abrufen	String (published; unpublished)
modified	nur überarbeitete Bewertungen werden abgerufen	Integer (0: nein; 1: ja)
ratingValueBelow	nur Bewertungen abrufen schlechter als x bewertet wurden	Float
ratingValueAbove	nur Bewertungen abrufen besser als x bewertet wurden	Float
createdBefore	alle Bewertungen abrufen die vor diesem Datum erstellt wurden	Integer (Timestamp)
createdAfter	alle Bewertungen abrufen die nach diesem Datum erstellt wurden	Integer (Timestamp)

Die Bewertungen sind absteigend nach Erstellungsdatum sortiert. Es werden nur Felder angezeigt, die Werte enthalten.

Response

Datenfeld	Beschreibung	Typ
status	Erfolg der Anfrage	String
ratings	Liste aller Bewertungen	Array
ratings.[n]	Datensatz einer Bewertung	Array
ratings.[n].created	Zeitpunkt der Abgabe der Bewertung	Integer (Timestamp)
ratings.[n].modified	Zeitpunkt der Überarbeitung der Bewertung	Integer (Timestamp)
ratings.[n].ratingValue	Gesamtbewertungrating dieser Bewertung	Float
ratings.[n].feedback	Feedback-Text	String
ratings.[n].status	Veröffentlichungsstatus	String (published; unpublished)
ratings.[n].recommendation	Ob der Kunde eine Empfehlung abgegeben hat	Integer (0. nein; 1: ja)
user	Informationen über den Bewerter	Array
user.name	Name des Bewerters	String
user.email	E-Mail Adresse des Bewerters (nur wenn der Bewerter per E-Mail eingeladen wurde)	String
topicCode	Code der Umfrage	String
ratings	Bewertungsdaten der einzelnen Oberkategorien der Umfrage	Array
ratingDetails	Bewertungsdaten zu jeder einzelnen Frage aus der Umfrage, geordnet nach Kategorien	Array
labels	Bezeichnung der Fragen	Array

rating/children

Enthalten in: ENTERPRISE

Ruft Bewertungen für alle Unterprofile (der nächst-tieferen Ebene) eines Enterprise-Accounts ab.

Request

Die Requestfelder entsprechen denen von rating/get.

Response

Der Response entspricht dem von rating/get, zusätzlich wird das Feld user.profileEmail mitgeliefert, das der E-Mail Adresse des Profils entspricht zu der die Bewertung gehört.

Datenfeld	Beschreibung	Typ
user.profileEmail	E-Mail Adresse des Profils	String

rating/summary/get

Request

// keine zusätzlichen Daten

Response

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

Enthalten in: ENTERPRISE PREMIUM PLUS BASIC FREE

Gesamtbewertung und Anzahl der Bewertungen des eigenen Profils.

Response

Datenfeld	Beschreibung	Typ
ratingValue	Gesamtbewertung des Profils	Float
reviewCount	Anzahl der Bewertung vom Profil	Integer

rating/summary/children

Request

// keine zusätzlichen Daten

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

Enthalten in: ENTERPRISE

Gesamtbewertung und Anzahl der Bewertungen aller Profile der nächstunteren Enterprise Ebene bzw. aller Profile die mit diesem User erstellt wurden.

Response

Datenfeld	Beschreibung	Typ
children	Liste aller Unterprofile	Array
children.[email]	Datensatz pro Profil	Array
children.[email].ratingValue	Gesamtbewertung des Profils	Float
children.[email].reviewCount	Anzahl der Bewertungen vom Profil	Integer

rating/summary/richsnippet

Request

<?php

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

Response

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

Enthalten in: ENTERPRISE PREMIUM PLUS

HTML Code des Rich Snippets für die Google Sterne erstellen.

Request

Datenfeld	Beschreibung	Typ	Default
version	Darstellungsart der Sterne	Integer (1,2,3,4)	1

Darstellungsarten der Sterne

Die Grafik zeigt die möglichen Darstellungsarten der Sterne und kann als Parameter version an die API übergeben werden. Wird der Parameter nicht angegeben, wird die erste Darstellungsart gewählt.

Eine Live-Vorschau der Darstellungsarten gibt es auf folgender Seite: Google-Sterne

Darstellungsarten der Sterne

Response

Datenfeld	Beschreibung	Typ
ratingValue	Gesamtbewertung des Profils	Float
reviewCount	Anzahl der Bewertung vom Profil	Integer
html	HTML Code des Rich Snippets	String

Authentifizierung

auth/url/get

Request

// keine zusätzlichen Daten

Response

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

Enthalten in: ENTERPRISE

Generiert eine Single Sign On URL mit der ein Login in das entsprechende Profil ohne Eingabe von E-Mail-Adresse und Passwort ermöglicht wird.

Der Link ist standardmäßig 10 Minuten gültig

Response

Datenfeld	Beschreibung	Typ
url	Link zum einloggen	String
expire	Timestamp, bis wann der Link gültig ist	Integer

auth/api/get

Request

// keine zusätzlichen Daten

Response

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

Enthalten in: ENTERPRISE

Gibt die Zugangsdaten für die ProvenExpert-API zurück.

In Verbindung mit einem Stellvertreter User lassen sich die API-Zugangsdaten für verschiedene Profile holen.

Response

Datenfeld	Beschreibung	Typ
id	API-ID für die Authentifizierung	String
key	API-Key für die Authentifizierung	String

auth/api/children

Request

// keine zusätzlichen Daten

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

Enthalten in: ENTERPRISE

Gibt die Zugangsdaten für die ProvenExpert-API von allen untergeordneten Profilen der nächstunteren Ebene zurück.

Response

Datenfeld	Beschreibung	Typ
children	Liste aller Unterprofile	Array
children.[n]	Datensatz pro Profil	Array
children.[n].id	API-ID für die Authentifizierung	String
children.[n].key	API-Key für die Authentifizierung	String

ProvenExpert API

Einführung

API-URL Struktur

URL Felder

Beispiele

Versionen

HTTP Methode

Datenformat

Authentifizierung

Request Struktur

Stellvertreter User

Rückgabewerte

Erfolgreiche Anfrage

Fehlerhafte Anfrage

Profile

profile/create

Request

Response

Profilbild

Profil-Headerbild

profile/update

Request

Response

Profilbild

Profil-Headerbild

profile/get

Response

profile/children

Response

profile/settings/update

Response

profile/settings/get

Response

profile/delete

Widget

widget/create

Request

Optionen für das Bewertungssiegel hochkant

Optionen für das Bewertungssiegel quadratisch

Optionen für das Bewertungssiegel quer

Optionen für das Qualitätssiegel

Optionen für das ProvenExpert-Logo

Optionen für das Bewertungssiegel am unteren Browser-Rand

Optionen für das Bewertungs-Widget

Optionen für die Award-Widgets

Response

Umfragen

survey/create

Request

Response

Point of Sale Umfrage (POS)

survey/update

Request

Response

Point of Sale Umfrage

survey/get

Response

Point of Sale Umfrage

Einladungen

invite/url/create

Request

Response

invite/url/get

Request

Response

invite/mail/create

Datenschutz

Erinnerungs E-Mail

Request

Response

invite/mail/status

Request

Response

Rating

rating/get

Request

Response

rating/children

Request

Response