Participant lists are required to invite participants to the survey via the easyfeedback email invitation tool. The participant lists and the entries (participants) in the lists can be read out or anonymized via the API. Please note that participant lists are technically used in two places in easyfeedback:
- As a “global” list of participants via the menu “Participant lists“
- As a list of participants added to the survey for “Email invitation“
Global participant lists of the entire account
This method provides access to all participant lists that have been created in the account.
|
URL |
/api/v2/participants/lists |
|||||||||||||||||||||
|
Methode |
GET |
|||||||||||||||||||||
|
Parameter |
page, limit |
|||||||||||||||||||||
|
Return |
JSON |
|||||||||||||||||||||
|
Return values |
|
Example: All participant lists:
<?php
// Get all participant lists
// getParticipantsLists.php
// v1.0.0
// Insert access token here
$accessToken = 'YOUR_ACCESS_TOKEN';
$apiUrl = 'https://app.easy-feedback.com/api/v2/participants/lists';
$ch = curl_init($apiUrl);
// cURL-Optionen konfigurieren
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $accessToken,
));
// Make a request
$response = curl_exec($ch);
// Display the result as JSON
if ($response === false) {
echo 'Error in the cURL request: ' . curl_error($ch);
} else {
$jsonData = json_decode($response, true);
if ($jsonData === null) {
echo 'Error decoding the JSON response.';
} else {
echo 'JSON response: <pre>' . json_encode($jsonData, JSON_PRETTY_PRINT) . "</pre>";
}
}
// Close cURL connection
curl_close($ch);
?>Participants of a global participant list
This method provides access to the participants that have been created in a global participant list.
|
URL |
/api/v2/participants/users |
||||||||||||||||||||||||||||||
|
Methode |
GET |
||||||||||||||||||||||||||||||
|
Parameter |
participantlistid, email, usercode, firstname, lastname, value1, value2, value3, value4, value5, page, limit |
||||||||||||||||||||||||||||||
|
Return |
JSON |
||||||||||||||||||||||||||||||
|
Return values |
|
Example: All participants from a participant list
<?php
// Get all participants from a participant list
// getParticipantsUsers.php
// v1.0.0
// access Token hier einfügen
$accessToken = 'YOUR_ACCESS_TOKEN';
// Filter participants by e.g. e-mail (replace emailfromparticipantslist@easy-feedback.de with your own e-mail from the participant list)
$participantlistid = '';
$email = 'emailfromparticipantslist@easy-feedback.de';
$usercode = '';
$firstname = '';
$lastname = '';
$value1 = '';
$value2 = '';
$value3 = '';
$value4 = '';
$value5 = '';
$page = '';
$limit = '';
$apiUrl = 'https://app.easy-feedback.com/api/v2/participants/users?participantlistid=' . $participantlistid .
'&email=' . urlencode($email) . '&usercode=' . urlencode($usercode) . '&firstname=' . urlencode($firstname) . '&lastname=' . urlencode($lastname) .
'&value1=' . urlencode($value1) . '&value2=' . urlencode($value2) . '&value3=' . urlencode($value3) . '&value4=' . urlencode($value4) .
'&value5=' . urlencode($value5) . '&page=' . $page . '&limit=' . $limit;
$ch = curl_init($apiUrl);
// Configure cURL options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $accessToken,
));
// Make a request
$response = curl_exec($ch);
// Display the result as JSON
if ($response === false) {
echo 'Error in the cURL request: ' . curl_error($ch);
} else {
$jsonData = json_decode($response, true);
if ($jsonData === null) {
echo 'Error decoding the JSON response.';
} else {
echo 'JSON response: <pre>' . json_encode($jsonData, JSON_PRETTY_PRINT) . "</pre>";
}
}
// Close cURL connection
curl_close($ch);
?>Additional columns (values) in the participant list
Any number of additional columns (values) can be added per participant within the participant list. This method can be used to query the additional columns.
|
URL |
/api/v2/participants/customvalues |
||||||||||||
|
Methode |
GET |
||||||||||||
|
Parameter |
participantlistid, page, limit |
||||||||||||
|
Rückgabe |
JSON |
||||||||||||
|
Return values |
|
User values of the additional fields in participant lists
This method can be used to read out the values of the additional columns for each participant.
|
URL |
/api/v2/participants/users/customvalues |
||||||||||||
|
Method |
GET |
||||||||||||
|
Parameter |
participantlistid, participantlistentryid, value, page, limit |
||||||||||||
|
Return |
JSON |
||||||||||||
|
Return values |
|
Example: All data from participant lists with linked user-defined values
// Get all data from participant list/s of a survey and link user-defined values
// getSurveysParticipantsListsEntryWithCustomValues.php
// v1.0.0
// Insert access token here
$accessToken = 'YOUR_ACCESS_TOKEN';
// Insert survey ID here
$surveyid = 'YOUR_SURVEYID';
// API-URLs
$apiUrl1 = 'https://app.easy-feedback.com/api/v2/surveys/participants/lists/entry/?surveyid=' . $surveyid;
$apiUrl2 = 'https://app.easy-feedback.com/api/v2/participants/users/customvalues';
// cURL initialization for participant list (participantslists)
$ch1 = curl_init($apiUrl1);
curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch1, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $accessToken,
));
$response1 = curl_exec($ch1);
if ($response1 === false) {
echo 'Error in the cURL request for participant list: ' . curl_error($ch1);
exit;
}
curl_close($ch1);
// cURL initialization for user-defined values (customvalues)
$ch2 = curl_init($apiUrl2);
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $accessToken,
));
$response2 = curl_exec($ch2);
if ($response2 === false) {
echo 'Error in the cURL request for user-defined values (customvalues): ' . curl_error($ch2);
exit;
}
curl_close($ch2);
// JSON-Daten dekodieren
$jsonData1 = json_decode($response1, true);
if ($jsonData1 === null) {
echo 'Error decoding the JSON response for participant list:.';
exit;
}
$jsonData2 = json_decode($response2, true);
if ($jsonData2 === null) {
echo 'Error decoding the JSON response for customvalues.';
exit;
}
// Linking the data
if ($jsonData1 && $jsonData2) {
foreach ($jsonData1['results'] as &$participantslists) {
$participantListUserId = $participantslists['ParticipantListUserId'];
$customValues = array_filter($jsonData2['results'], function ($customValue) use ($participantListUserId) {
return $customValue['ParticipantListUserId'] === $participantListUserId;
});
// Add the values of the custom values directly to $participantslists
$i = 1;
foreach ($customValues as $customValue) {
$participantslists['Value' . $i++] = $customValue['Value'];
}
}
}
// Output of the combined JSON
echo 'JSON answer: <pre>' . json_encode($jsonData1, JSON_PRETTY_PRINT) . "</pre>";
?>Example: All data from participant lists with link to user-defined values from the participant list
<?php
// Get all data from participant list(s) and link user-defined values (custom values)
// getParticipantsUsersWithCustomValues.php
// v1.0.0
// Insert access token here
$accessToken = 'YOUR_ACCESS_TOKEN';
// Insert participant list ID here
$participantlistid = 'YOUR_PARTICIPANT_LIST_ID';
// API-URLs
$apiUrl1 = 'https://app.easy-feedback.com/api/v2/participants/users/?participantlistid=' . $participantlistid;
$apiUrl2 = 'https://app.easy-feedback.com/api/v2/participants/users/customvalues/?participantlistid=' . $participantlistid;
// cURL initialization for participant list (participantslists)
$ch1 = curl_init($apiUrl1);
curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch1, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $accessToken,
));
$response1 = curl_exec($ch1);
if ($response1 === false) {
echo 'Error in the cURL request for participants lists: ' . curl_error($ch1);
exit;
}
curl_close($ch1);
// cURL initialization for user-defined values (custom values)
$ch2 = curl_init($apiUrl2);
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $accessToken,
));
$response2 = curl_exec($ch2);
if ($response2 === false) {
echo 'Error in the cURL request for user-defined values (customvalues): ' . curl_error($ch2);
exit;
}
curl_close($ch2);
// Decode JSON data
$jsonData1 = json_decode($response1, true);
if ($jsonData1 === null) {
echo 'Error decoding the JSON response for participants lists:.';
exit;
}
$jsonData2 = json_decode($response2, true);
if ($jsonData2 === null) {
echo 'Error decoding the JSON response for customvalues.';
exit;
}
// Linking the data
if ($jsonData1 && $jsonData2) {
foreach ($jsonData1['results'] as &$participantsusers) {
$participantListUserId = $participantsusers['Id'];
$customValues = array_filter($jsonData2['results'], function ($customValue) use ($participantListUserId) {
return $customValue['ParticipantListUserId'] === $participantListUserId;
});
// Add the values of the custom values directly to $participantsusers
$i = 1;
foreach ($customValues as $customValue) {
$participantsusers['Value' . $i++] = $customValue['Value'];
}
}
}
// Output of the combined JSON
echo 'JSON-Antwort: <pre>' . json_encode($jsonData1, JSON_PRETTY_PRINT) . "</pre>";
?>Participant lists added under email invitation
This method provides access to the participant lists that are assigned to a survey under “Invite participants” for email invitations.
|
URL |
/api/v2/surveys/participants/lists |
|||||||||
|
Methode |
GET |
|||||||||
|
Parameter |
surveyid, page, limit |
|||||||||
|
Return |
JSON |
|||||||||
|
Return values |
|
Participants in a list under email invitations
This method provides access to all participants in a participant list who have taken part in a survey. The surveyid parameter is mandatory for this method!
|
URL |
/api/v2/surveys/participants/lists/entry |
||||||||||||||||||||||||||||||||||||||||||
|
Method |
GET |
||||||||||||||||||||||||||||||||||||||||||
|
Parameter |
surveyid (required), surveyparticipantlistid, email, usercode, firstname, lastname, value1, value2, value3, value4, value5, page, limit |
||||||||||||||||||||||||||||||||||||||||||
|
Return |
JSON |
||||||||||||||||||||||||||||||||||||||||||
|
Return values |
|
Example: All participants in a survey with a link to user-defined values from the participant list
<?php
// Get all participants of a survey and link user-defined values (custom values) from the participant lists
// getMembersWithCustomValues.php
// v1.1.0
// Insert access token here
$accessToken = 'YOUR_ACCESS_TOKEN';
// Insert survey ID here
$surveyid = 'YOUR_SURVEYID';
// Base URL for API
$baseUrl = 'https://app.easy-feedback.com';
// Retrieve API URL for the participants
$apiUrl1 = $baseUrl . '/api/v2/members?surveyid=' . $surveyid;
echo "Get participant: " . $apiUrl1;
// cURL initialization for participants
$ch1 = curl_init($apiUrl1);
curl_setopt($ch1, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch1, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $accessToken,
));
$response1 = curl_exec($ch1);
if ($response1 === false) {
echo 'Error in the cURL request for participants: ' . curl_error($ch1);
exit;
}
curl_close($ch1);
// Decode JSON data
$jsonData1 = json_decode($response1, true);
if ($jsonData1 === null) {
echo 'Error decoding the JSON response for participants.';
exit;
}
// Initialize an empty array for the custom values
$customValues = [];
// Retrieve and link API URLs for the custom values
if (isset($jsonData1['results']) && is_array($jsonData1['results'])) {
foreach ($jsonData1['results'] as $participant) {
// 1 second pause between API calls
sleep(1);
$participantlistid = $participant['ParticipantListId'];
// Check whether a Participant List ID has been used
if ($participantlistid > 0 && !isset($customValues[$participantlistid])) {
$apiUrl2 = $baseUrl . '/api/v2/participants/users/customvalues?participantlistid=' . $participantlistid;
echo "<br>Get user-defined values: " . $apiUrl2;
// cURL initialization for custom values
$ch2 = curl_init($apiUrl2);
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_HTTPHEADER, array(
'Authorization: Bearer ' . $accessToken,
));
$response2 = curl_exec($ch2);
if ($response2 === false) {
echo 'Error in the cURL request for custom values: ' . curl_error($ch2);
exit;
}
curl_close($ch2);
// Decode JSON data and add to $customValues
$decodedResponse = json_decode($response2, true);
if ($decodedResponse === null) {
echo 'Error decoding the JSON response for custom values.';
exit;
} else {
// Add the results from each run of the loop to $customValues
if (isset($decodedResponse['results'])) {
$customValues[$participantlistid] = $decodedResponse['results'];
}
}
}
}
}
// Linking the data
if ($jsonData1 && $customValues) {
foreach ($jsonData1['results'] as &$member) {
$participantListUserId = $member['ParticipantListUserId'];
$participantlistid = $member['ParticipantListId'];
if (isset($customValues[$participantlistid])) {
$memberCustomValues = array_filter($customValues[$participantlistid], function ($customValue) use ($participantListUserId) {
return $customValue['ParticipantListUserId'] === $participantListUserId;
});
// Füge die Werte der Custom Values direkt zu $member hinzu
$i = 1;
foreach ($memberCustomValues as $customValue) {
$member['Value' . $i++] = $customValue['Value'];
}
}
}
}
// Output of the combined JSON
echo '<br><br>JSON response: <pre>' . json_encode($jsonData1, JSON_PRETTY_PRINT) . "</pre>";
?>