MENÜ
Code-Beispiele / Rückgabewerte

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:

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

Bitte beachten: diese Funktion steht Ihnen erst ab dem ENTERPRISE-Paket zur Verfügung.

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

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

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

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 gesamte Bildbreite geht.

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

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

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

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

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

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.

Widget

widget/create

Request

<?php

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

Response

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

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

Bewertungssiegel hochkant Bewertungssiegel als Slider

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

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

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

Qualitätssiegel

Datenfeld Beschreibung Typ Default
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

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

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

Optionen für das Bewertungs-Widget

Bewertungs-Widget

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

Award Beispiele

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

Datenfeld Beschreibung Typ Default
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>"
    }
}

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

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

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

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

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
}

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

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

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

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

Bitte beachten: diese Funktion steht Ihnen erst ab dem PREMIUM-Paket zur Verfügung.

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 die mind. mit x bewertet wurden Float
ratingValueAbove nur Bewertungen abrufen besser als mit 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

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
}

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

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

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
}

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

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

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