API

Eine Schnittstelle, viele Möglichkeiten

Umfrageergebnisse

Um die Teilnehmerdaten und Ergebnisse abzufragen, bietet die easyfeedback API V2 drei unterschiedliche Möglichkeiten:

  1. members: alle Metadaten zu einem oder sämtlichen Teilnehmern
  2. dataexport: alle Ergebnisse eines Teilnehmers aus einer Umfrage
  3. results: alle Ergebnisse aus einer oder sämtlichen Umfragen

Members: Metadaten eines Teilnehmers

Diese Methode bietet Zugriff auf die Teilnehmer einer Umfrage und beinhaltet die Metadaten zu jedem einzelnen Teilnehmer.

Parameter: pkey & pval
Die Parameter „pkey“ und „pval“ dienen dazu, das Suchergebnis auf bestimmte URL-Parameter einzugrenzen, die an die Umfrage-URL angehängt wurden.

Paramter: newer
Das Setzen des Parameters „newer“ hat folgende Auswirkungen:

  • Mit „memberid“ werden alle Datensätze geliefert, die neuer als die angegebene
    „memberid“ sind.
  • Ohne „memberid“ werden alle Datensätze geliefert, die seit der letzten Abfrage hinzugekommen sind.
  • Wird keine „memberid“ gesetzt, aber status = 1 (beendet), dann werden alle Datensätze seit der letzten Abfrage geliefert, deren Endzeit größer als der Zeitpunkt der letzte Abfrage war.
  • Wird keine „memberid“ gesetzt, aber status != 1 (beendet), dann werden alle Datensätze seit der letzten Abfrage geliefert, deren Startzeit größer als der Zeitpunkt der letzte Abfrage war.

Parameter: updatedts
Das Setzen des Parameters „updatedts“ mit einem Unixtimestamp liefert alle Datensätze, die seit dem angegebenen Datum aktualisiert wurden. Diese Abfrage eignet sich sehr gut dazu, um nur Datensätze zu ziehen, die aktualisiert wurden, bzw. neu hinzugekommen sind. Zudem können im Fehlerfall die Ergebnisse seit einem bestimmten Datum erneut aufgerufen werden.

Zeitangaben:
Zeiten sind als Datum im Atom-Format angegeben. „StartDate“ ist der Zeitpunkt des Aufrufs der Umfrage, „Votetime“ die Zeit, die insgesamt zwischen den Seitenaufrufen vergangen ist, „EndDate“ der Zeitpunkt, zu dem die Umfrage zuletzt beendet wurde. Bitte beachte Sie, dass ein Zeitraum von mehr als 15 Minuten zwischen zwei Seitenaufrufen nicht mehr zu der Gesamtzeit (Votetime) hinzugerechnet wird, da bei größeren Pausen während der Teilnahme die Gesamtzeit grob verfälscht werden würde.

URL

/api/v2/members

Methode

GET, PUT

GET Parameter

surveyid, languageid, statusid, participantlistid, participantuserid, refererid, personalid, deviceid, newer, pkey, pval, updatedts, page, limit

PUT Parameter

Die memberId des anzupassenden Datensatz kann an den API-Aufruf angehängt werden (/api/v2/members/[memberid] ). Wird auch im Payload eine MemberId mitgegeben, so wird die MemberId in der Url ignoriert.

Input type

JSON im Body

Rückgabe

JSON

Rückgabewerte

Id

int

ID des Datensatzes

SurveyId

int

ID der Umfrage

LanguageId

int

ID der Sprache

StatusId

int

Aktueller Teilnahmestatus des Teilnehmers
0 – Besucher – noch keine Antworten gegeben
1 – Beendet
2 – Laufende oder abgebrochene Umfrage

ParticipantListId

int

ID der Teilnehmerliste

ParticipantUserId

int

ID des Teilnehmers in der Teilnehmerliste

SurveyParticipantListId

int

ID der Teilnehmerliste aus der E-Mail Einladung

SurveyParticipantUserId

int

ID des Teilnehmers in der Teilnehmerliste aus der E-Mail Einladung

RefererId

int

Über welche Quelle die Umfrage durch den Teilnehmer aufgerufen wurde
0 – Direkter Aufruf der URL
1 – Aufruf per Weblink
2 – Website-Einbindung (z.B. iFrame)
3 – Umfrage-Popup
4 – Nicht feststellbar

MultilinkId

int

ID des verwendeten Multilinks

PersonalId

str

Persönliche ID, falls sie in der URL gesetzt wurde

DeviceId

int

Verwendetes Endgerät zur Teilnahme an der Umfrage
0 – Unbekannt
1 – Web
2 – Tablet
3 – Mobil

AccessCode

str

Zugangscode für die Umfrage

Pos

int

Aktuelle Position des Teilnehmers in der Umfrage
0 – Begrüßungsseite oder noch nicht teilgenommen
1 – Erste Seite der Umfrage
n – Seite n
999 – Letzte Seite

LastUpdate

date

Letzte Aktualisierung der Umfragedaten des Teilnehmers

Votetime

int

Gesamtzeit der Teilnahme

StartDate

date

Anfangszeit der Teilnahme an der Umfrage

EndDate

date

Zeit bei Beendigung der Umfrage durch den Teilnehmer

VoucherCode

int

Gutscheincode, der in der Umfrage ausgehändigt wurde

UrlReference

int

URL von der der Teilnehmer auf die Umfrage geleitet wurde

UrlParameters

int

Individuelle Parameter am Umfragelink zu dem Teilnehmer

Points

int

Anzahl der Quiz-Punkte

MaxPoints

int

Maximalanzahl der Quiz-Punkte

Questions

int

Anzahl der richtigen Antworten

MaxPoints

int

Maximalanzahl der richtigen Antworten

Beispielanfrage:
Anfrage: https://app.easy-feedback.com/api/v2/members/4771

Payload:

JSON
[
   {
      "Personalid": "ABD3438332333231"
   }
]

Ergebnis:
Siehe Ergebnis GET

Beispiel: Alle Teilnehmer einer Umfrage
PHP
<?php

// Alle Teilnehmer einer Umfrage
// getAllMembers.php
// v1.0.0

// access Token hier einfügen
$accessToken = 'YOUR_ACCESS_TOKEN';

// Umfrage ID hier einfügen
$surveyid = 'YOUR_SURVEYID';

$apiUrl = 'https://app.easy-feedback.com/api/v2/members?surveyid=' . $surveyid;

$ch = curl_init($apiUrl);

// cURL-Optionen konfigurieren
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ' . $accessToken,
));

// Anfrage durchführen
$response = curl_exec($ch);

// Das Ergebnis als JSON anzeigen
if ($response === false) {
    echo 'Fehler bei der cURL-Anfrage: ' . curl_error($ch);
} else {
    $jsonData = json_decode($response, true);
    if ($jsonData === null) {
        echo 'Fehler beim Dekodieren der JSON-Antwort.';
    } else {
        echo 'JSON-Antwort: <pre>' . json_encode($jsonData, JSON_PRETTY_PRINT) . "</pre>";
    }
}

// cURL-Verbindung schließen
curl_close($ch);

?>

Dataexport: alle Ergebnisse eines Teilnehmers

Diese Methode stellt die Daten eines Teilnehmers in aufbereiteter Form zur Verfügung. Die Antwort beinhaltet sowohl Frage- und Antwort-Texte der beantworteten Fragen, als auch die vom Teilnehmer gegebenen Antworten. Sowohl Ergebnisse als auch Antworten werden als Array zurückgegeben.

URL

/api/v2/members/dataexport/[memberid]

Methode

GET

Parameter

Memberid

Rückgabe

JSON

Beispielanfrage:
https://app.easy-feedback.com/api/v2/members/dataexport/1

Ergebnis:

JSON
{
	"0": {
		"title": "Nutzen Sie das erste Mal unsere API?",
		"id": "280",
		"results": {
			"0": "Ja"
		}
	},
	"1": {
		"title": "Welche Farbe dominiert im easy-feedback Logo?",
		"id": "283",
		"results": {
			"0": "",
			"1": "Rot",
			"2": ""
		},
		"answers": {
			"0": "Blau",
			"1": "Rot",
			"2": "Gelb"
		}
	}
}

Results: alle Ergebnisse abfragen

Diese Methode liefert alle Ergebnisse in Form von IDs zurück. Damit lassen sich sämtliche Ergebnisse zu einzelnen Umfrage auslesen. Der surveyid Parameter ist bei dieser Methode verpflichtend!

Zu beachten: Die Rückgabe ist auf 1000 Ergebnisse begrenzt. Daher sind bei der Abfrage ein oder mehrere Parameter zu setzen. Zum einen sollte immer die „surveyid“ gesetzt werden, um die Abfrage auf eine Umfrage zu begrenzen. Und mit dem Parameter „page“ und „limit“ kann die Abfrage zusätzlich eingegrenzt werden, um das Limit von 1000 nicht zu überschreiten. Der surveyid Parameter ist bei dieser Methode verpflichtend!

URL

/api/v2/results

Methode

GET

Parameter

surveyid (verpflichtend), questionid, answerid, levelid, answertext, memberid, page, limit

Rückgabe

JSON

Rückgabewerte

Id

int

ID des Datensatzes, nur eindeutig in Verbindung mit Type

Type

str

Ergebnistyp, mögliche Werte sind String, Integer, NotAnswered

MemberId

int

ID des Umfrage-Teilnehmers

QuestionId

int

ID der Frageseite

AnswerId

int

ID der Antwort

LevelId

int

ID, wenn es bei den Antworten Abstufungen gibt, wie z. B. bei der Matrix-Frage

Row

int

Zeile (Item) z.B. bei einer Matrix-Frage

Column

int

Bewertungs-Spalte z.B. bei einer Matrix-Frage

Section

int

Bereich bei Doppelmatrix-Fragen (1=links 2=rechts)

Text

str

Textstring der Antwort, falls gegeben

Beispiel: Alle Ergebnisse einer Umfrage
PHP
<?php

// Alle Ergebnisse einer Umfrage
// getAllResults.php
// v1.0.1

// access Token hier einfügen
$accessToken = 'YOUR_ACCESS_TOKEN';

// Umfrage ID hier einfügen
$surveyid = 'YOUR_SURVEYID';

$apiUrl = 'https://app.easy-feedback.com/api/v2/results?surveyid=' . $surveyid;

$ch = curl_init($apiUrl);

// cURL-Optionen konfigurieren
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ' . $accessToken,
));

// Anfrage durchführen
$response = curl_exec($ch);

// Das Ergebnis als JSON anzeigen
if ($response === false) {
    echo 'Fehler bei der cURL-Anfrage: ' . curl_error($ch);
} else {
    $jsonData = json_decode($response, true);
    if ($jsonData === null) {
        echo 'Fehler beim Dekodieren der JSON-Antwort.';
    } else {
        echo 'JSON-Antwort: <pre>' . json_encode($jsonData, JSON_PRETTY_PRINT)."</pre>";
    }
}

// cURL-Verbindung schließen
curl_close($ch);

?>
Beispiel: Ergebnisse für Teilnehmer X einer Umfrage
PHP
<?php

// Ergebnisse für Teilnehmer X einer Umfrage
// getAllResultsByMemberId.php
// v1.0.1

// access Token hier einfügen
$accessToken = 'YOUR_ACCESS_TOKEN';

// Umfrage ID hier einfügen
$surveyid = 'YOUR_SURVEYID';
// Teilnehmer ID hier eintragen
$memberid = 'YOUR_MEMBERID';

$apiUrl = 'https://app.easy-feedback.com/api/v2/results?surveyid=' . $surveyid . '&memberid=' . $memberid;

$ch = curl_init($apiUrl);

// cURL-Optionen konfigurieren
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ' . $accessToken,
));

// Anfrage durchführen
$response = curl_exec($ch);

// Das Ergebnis als JSON anzeigen
if ($response === false) {
    echo 'Fehler bei der cURL-Anfrage: ' . curl_error($ch);
} else {
    $jsonData = json_decode($response, true);
    if ($jsonData === null) {
        echo 'Fehler beim Dekodieren der JSON-Antwort.';
    } else {
        echo 'JSON-Antwort: <pre>' . json_encode($jsonData, JSON_PRETTY_PRINT)."</pre>";
    }
}

// cURL-Verbindung schließen
curl_close($ch);

?>
Beispiel: Alle Ergebnisse einer Umfrage von Tag X bis Tag Y
PHP
<?php

// Alle Ergebnisse einer Umfrage von Tag X bis Tag Y
// getAllResultsFromDate.php
// v1.0.1

// access Token hier einfügen
$accessToken = 'YOUR_ACCESS_TOKEN';

// Umfrage ID hier einfügen
$surveyid='YOUR_SURVEYID';

// Datumsbereich JJJJ-MM-TT
$startDateFilter = '2020-01-01';
$endDateFilter = '2030-12-30';

$apiUrl = 'https://app.easy-feedback.com/api/v2/members?surveyid=' . $surveyid;
$apiUrl2 = 'https://app.easy-feedback.com/api/v2/results?surveyid=' . $surveyid;


$ch = curl_init($apiUrl);

// cURL-Optionen konfigurieren
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ' . $accessToken,
));

// Anfrage durchführen
$response1 = curl_exec($ch);

// Das Ergebnis als JSON anzeigen
if ($response1 === false) {
    echo 'Fehler bei der cURL-Anfrage: ' . curl_error($ch);
} else {
    $jsonData1 = json_decode($response1, true);
    if ($jsonData1 === null) {
        echo 'Fehler beim Dekodieren der JSON-Antwort für API 1.';
    } else {
		// Prüfen ob Ergebnisse vorhanden
		if (!array_key_exists('results',$jsonData1))
		{
			// Das Ergebnis als JSON anzeigen
			echo "<pre>" . json_encode($jsonData1, JSON_PRETTY_PRINT) . "</pre>";
			exit;
		}

		// Nur Ergebnisse im angegebenen Zeitraum auswählen
		$selectedResultsApi1 = array_filter($jsonData1['results'], function($result) use ($startDateFilter, $endDateFilter) {
            if (isset($result['StartDate'])) {
                $startDate = date('Y-m-d', strtotime($result['StartDate']));
                return $startDate >= $startDateFilter && $startDate <= $endDateFilter;
            }
            return false;
        });
		
        $memberIdsApi1 = array_map(function ($result) {
            return $result['Id'];
        }, $selectedResultsApi1);		
    }
}

// cURL-Verbindung schließen
curl_close($ch);

$ch2 = curl_init($apiUrl2);

// cURL-Optionen konfigurieren
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ' . $accessToken,
));

// Anfrage durchführen
$response2 = curl_exec($ch2);

// Das Ergebnis als JSON anzeigen
if ($response2 === false) {
    echo 'Fehler bei der cURL-Anfrage: ' . curl_error($ch2);
} else {
    $jsonData2 = json_decode($response2, true);
    if ($jsonData2 === null) {
        echo 'Fehler beim Dekodieren der JSON-Antwort für API 2.';
    } else {
        // Ergebnisse aus der zweiten API-Abfrage auswählen, die in der ersten API-Abfrage vorhanden sind
        $selectedResultsApi2 = array_filter($jsonData2['results'], function ($result) use ($memberIdsApi1) {
            return in_array($result['MemberId'], $memberIdsApi1);
        });
        
        // Ggf. numerische Indizes entfernen
	      $selectedResultsApi2 = array_values($selectedResultsApi2);

        // Das Ergebnis als JSON anzeigen
        echo "<pre>" . json_encode($selectedResultsApi2, JSON_PRETTY_PRINT) . "</pre>";
    }
}

// cURL-Verbindung schließen
curl_close($ch2);

?>
Beispiel: Alle Ergebnisse einer Umfrage wo die Antwort ID X gegeben wurde
PHP
<?php

// Alle Ergebnisse einer Umfrage wo die Antwort ID X gegeben wurde
// getAllResultsWithAnswerIdX.php
// v1.0.1

// access Token hier einfügen
$accessToken = 'YOUR_ACCESS_TOKEN';

// Umfrage ID hier einfügen
$surveyid = 'YOUR_SURVEYID';
// Die zu suchende ID 
$answerid = "2";

$apiUrl = 'https://app.easy-feedback.com/api/v2/results?surveyid=' . $surveyid . "&answerid=" . $answerid;

$ch = curl_init($apiUrl);

// cURL-Optionen konfigurieren
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ' . $accessToken,
));

// Anfrage durchführen
$response = curl_exec($ch);

// Das Ergebnis als JSON anzeigen
if ($response === false) {
    echo 'Fehler bei der cURL-Anfrage: ' . curl_error($ch);
} else {
    $jsonData = json_decode($response, true);
    if ($jsonData === null) {
        echo 'Fehler beim Dekodieren der JSON-Antwort.';
    } else {
        echo 'JSON-Antwort: <pre>' . json_encode($jsonData, JSON_PRETTY_PRINT)."</pre>";
    }
}

// cURL-Verbindung schließen
curl_close($ch);

?>
Beispiel: Alle Ergebnisse einer Umfrage wo Antworttext X gegeben wurde
PHP
<?php

// Alle Ergebnisse einer Umfrage wo Antworttext X gegeben wurde
// getAllResultsWithAnswerTextX.php
// v1.0.1

// access Token hier einfügen
$accessToken = 'YOUR_ACCESS_TOKEN';

// Umfrage ID hier einfügen
$surveyid = 'YOUR_SURVEYID';
// Der zu suchende Text einer Textfrage
$answertext = "YOUR_TEXT";

$apiUrl = 'https://app.easy-feedback.com/api/v2/results?surveyid=' . $surveyid . "&answertext=" . urlencode($answertext);

$ch = curl_init($apiUrl);

// cURL-Optionen konfigurieren
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ' . $accessToken,
));

// Anfrage durchführen
$response = curl_exec($ch);

// Das Ergebnis als JSON anzeigen
if ($response === false) {
    echo 'Fehler bei der cURL-Anfrage: ' . curl_error($ch);
} else {
    $jsonData = json_decode($response, true);
    if ($jsonData === null) {
        echo 'Fehler beim Dekodieren der JSON-Antwort.';
    } else {
        echo 'JSON-Antwort: <pre>' . json_encode($jsonData, JSON_PRETTY_PRINT)."</pre>";
    }
}

// cURL-Verbindung schließen
curl_close($ch);

?>

Bereit zu starten? Erstellen Sie jetzt großartige Umfragen!