API

One interface, many possibilities

Participant lists

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:

  1. As a “global” list of participants via the menu “Participant lists
  2. 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

Id

int

ID of the data record

CustomerId

int

ID of the customer

GroupId

int

ID of the group

Name

str

Name of the list

Participants

int

Number of the participants

CreatedAt

date

Create date

UpdatedAt

date

Last update date

Example: All participant lists:
PHP
<?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

Id

int

ID of the data record

ParticipantListId

int

ID of the participant list

Email

str

Email

Title

str

Title

FirstName

str

Firstname

LastName

str

Lastname

ReferenceText

str

Value from “Reference text” column

AccessCode

str

Access code for survey

CreatedAt

date

Create date

UpdatedAt

date

Change date

Example: All participants from a participant list
PHP
<?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

ID

int

Data record ID

ParticipantListId

int

ID of the participant list

Name

str

Name of the field

Position

int

Position of the field

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

Id

int

Data record ID

ParticipantListUserId

int

ID of the participant in the participant list

ParticipantListCustomId

int

ID of the additional field

Value

str

Value saved in the additional field for the participant

Example: All data from participant lists with linked user-defined values
PHP
// 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
<?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

Id

int

ID of the data record

SurveyId

int

Survey ID

Name

str

Name of the list

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

Id

int

ID of the data record

SurveyParticipantListId

int

ID of the survey participant list

SurveyParticipantListUserId

int

ID of the participant in the survey participant list

MemberId

int

ID of the survey participant

ParticipantUserCode

str

User code that was set in the participant list

Email

str

Email

Title

str

Title

FirstName

str

Firstname

LastName

str

Lastname

ReferenceText

str

Value from “Reference text” column

AccessCode

str

Access code for survey

SendDate1

date

Date of the first invitation

SendDate2

date

Date of the second invitation

SendDate3

date

Date of the third invitation

Example: All participants in a survey with a link to user-defined values from the participant list
PHP
<?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>";

?>

Ready to start? Create great surveys now!