API

One interface, many possibilities

Survey results

The easyfeedback API V2 offers three different options for retrieving participant data and results:

  1. members: all metadata for one or all participants
  2. dataexport: all results of a participant from a survey
  3. results: all results from one or all surveys

Members: Metadata of a participant

This method provides access to the participants of a survey and contains the metadata for each individual participant.

Parameter: pkey & pval
The parameters “pkey” and “pval” are used to limit the search result to certain URL parameters that were appended to the survey URL.

Paramter: newer
Setting the “newer” parameter has the following effects:

  • With “memberid”, all data records are delivered that are newer than the specified “memberid” are returned.
  • Without “memberid”, all data records that have been added since the last query are returned.
  • If no “memberid” is set, but status = 1 (completed), then all data records since the last query whose end time was greater than the time of the last query are returned.
  • If no “memberid” is set, but status != 1 (completed), then all data records since the last query whose start time was greater than the time of the last query are returned.

Parameter: updatedts
Setting the parameter “updatedts” with a Unixtimestamp returns all data records that have been updated since the specified date. This query is very suitable for pulling only data records that have been updated or newly added. In addition, the results since a certain date can be called up again in the event of an error.

Time information:
Times are given as dates in Atom format. “StartDate” is the time at which the survey was started, “Votetime” is the total time that has elapsed between page views, “EndDate” is the time at which the survey was last completed. Please note that a period of more than 15 minutes between two page views is no longer added to the total time (Votetime), as the total time would be grossly distorted if there were longer breaks during participation.

URL

/api/v2/members

Method

GET, PUT

GET Parameter

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

PUT Parameter

The memberId of the data set to be adjusted can be appended to the API call ( /api/v2/members/[memberid] ). If a memberId is also specified in the payload, the memberId in the url is ignored.

Input type

JSON im Body

Return

JSON

Return values

Id

int

ID of the data record

SurveyId

int

ID of the survey

LanguageId

int

ID of the language

StatusId

int

Current status of the participant
0 – Visitor – no answers given yet
1 – Finished
2 – Ongoing or canceled survey

ParticipantListId

int

ID of the participant list

ParticipantUserId

int

ID of the participant in the participant list

SurveyParticipantListId

int

ID of the participant list from the e-mail invitation

SurveyParticipantUserId

int

ID of the participant in the participant list from the e-mail invitation

RefererId

int

From which source the survey was accessed by the participant
0 – Direct access to the URL
1 – Call via web link
2 – Website integration (e.g. iFrame)
3 – Survey pop-up
4 – Not detectable

MultilinkId

int

ID of the multilink used

PersonalId

str

Personal ID, if it was set in the URL

DeviceId

int

Device type that has used to participate in the survey
0 – Unknown
1 – Web
2 – Tablet
3 – Mobile

AccessCode

str

Access code for the survey

Pos

int

Current position of the participant in the survey
0 – Welcome page or not yet participated
1 – First page of the survey
n – Page n
999 – Last page

LastUpdate

date

Last update of the participant’s survey data

Votetime

int

Total votetime of the participant

StartDate

date

Start time of participation in the survey

EndDate

date

Time at the end of the survey by the participant

VoucherCode

int

Voucher code handed out in the survey

UrlReference

int

URL from which the participant was directed to the survey

UrlParameters

int

Individual parameters, if it was set in the URL

Points

int

Number of quiz points

MaxPoints

int

Maximum number of quiz points

Questions

int

Number of correct answers

MaxPoints

int

Maximum number of correct answers

Example request:
Request: https://app.easy-feedback.com/api/v2/members/4771

Payload:

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

Result:
See result GET

Example: All participants of a survey
PHP
<?php

// All participants of a survey
// getAllMembers.php
// v1.0.0

// Insert access token here
$accessToken = 'YOUR_ACCESS_TOKEN';

// Insert survey ID here
$surveyid = 'YOUR_SURVEYID';

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

$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);

?>

Data export: all results of a participant

This method makes a participant’s data available in edited form. The response contains both the question and answer texts of the questions answered, as well as the answers given by the participant. Both results and answers are returned as an array.

URL

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

Method

GET

Parameter

Memberid

Return

JSON

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

Result:

JSON
{
	"0": {
		"title": "Are you using our API for the first time?",
		"id": "280",
		"results": {
			"0": "Yes"
		}
	},
	"1": {
		"title": "Which color dominates the easy-feedback logo?",
		"id": "283",
		"results": {
			"0": "",
			"1": "Red",
			"2": ""
		},
		"answers": {
			"0": "Blue",
			"1": "Red",
			"2": "Yellow"
		}
	}
}

Results: get all results

This method returns all results in the form of IDs. This allows to read out all results for individual surveys. The surveyid parameter is mandatory for this method!

Please note: The return is limited to 1000 results. Therefore, one or more parameters must be set for the query. Firstly, the “surveyid” should always be set to limit the query to one survey. And with the “page” and “limit” parameters, the query can also be limited so that the limit of 1000 is not exceeded. The surveyid parameter is mandatory for this method!

URL

/api/v2/results

Method

GET

Parameter

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

Return

JSON

Return values

Id

int

ID of the data record, only unique in connection with Type

Type

str

Result type, possible values are String, Integer, NotAnswered

MemberId

int

ID of the survey participant

QuestionId

int

ID of the question page

AnswerId

int

ID of the answer

LevelId

int

ID if there are gradations in the answers, such as in the matrix question

Row

int

Line (item) e.g. for a matrix question

Column

int

Rating column e.g. for a matrix question

Section

int

Range for double matrix questions (1=left 2=right)

Text

str

Text string of the answer, if given

Example: All results of a survey
PHP
<?php

// All results of a survey
// getAllResults.php
// v1.0.1

// Insert access token here
$accessToken = 'YOUR_ACCESS_TOKEN';

// Insert survey ID here
$surveyid = 'YOUR_SURVEYID';

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

$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 with 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);

?>
Example: The results for participant X of a survey
PHP
<?php

// The results for participant X of a survey
// getAllResultsByMemberId.php
// v1.0.1

// Insert access token here
$accessToken = 'YOUR_ACCESS_TOKEN';

// Insert survey ID here
$surveyid = 'YOUR_SURVEYID';
// Enter participant ID here
$memberid = 'YOUR_MEMBERID';

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

$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);

?>
Example: All results of a survey from day X to day Y
PHP
<?php

// All results of a survey from day X to day Y
// getAllResultsFromDate.php
// v1.0.1

// Insert access token here
$accessToken = 'YOUR_ACCESS_TOKEN';

// Insert survey ID here
$surveyid='YOUR_SURVEYID';

// Date range YYYY-MM-DD
$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);

// Configure cURL options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ' . $accessToken,
));

// Make a request
$response1 = curl_exec($ch);

// Display the result as JSON
if ($response1 === false) {
    echo 'Error with the cURL request: ' . curl_error($ch);
} else {
    $jsonData1 = json_decode($response1, true);
    if ($jsonData1 === null) {
        echo 'Error decoding the JSON response for API 1.';
    } else {
		// Check whether results are available
		if (!array_key_exists('results',$jsonData1))
		{
			// Display the result as JSON
			echo "<pre>" . json_encode($jsonData1, JSON_PRETTY_PRINT) . "</pre>";
			exit;
		}

		// Only select results in the specified period
		$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);		
    }
}

// Close cURL connection
curl_close($ch);

$ch2 = curl_init($apiUrl2);

// Configure cURL options
curl_setopt($ch2, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch2, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ' . $accessToken,
));

// Carry out enquiry
$response2 = curl_exec($ch2);

// Display the result as JSON
if ($response2 === false) {
    echo 'Error in the cURL request: ' . curl_error($ch2);
} else {
    $jsonData2 = json_decode($response2, true);
    if ($jsonData2 === null) {
        echo 'Error decoding the JSON response for API 2.';
    } else {
        // Select results from the second API query that are present in the first API query
        $selectedResultsApi2 = array_filter($jsonData2['results'], function ($result) use ($memberIdsApi1) {
            return in_array($result['MemberId'], $memberIdsApi1);
        });
        
        // Remove numerical indices if applicable
        $selectedResultsApi2 = array_values($selectedResultsApi2);

        // Display the result as JSON
        echo "<pre>" . json_encode($selectedResultsApi2, JSON_PRETTY_PRINT) . "</pre>";
    }
}

// Close cURL connection
curl_close($ch2);

?>
Example: All results of a poll where the answer ID X was given
PHP
<?php

// All results of a poll where the answer ID X was given
// getAllResultsWithAnswerIdX.php
// v1.0.1

// Insert access token here
$accessToken = 'YOUR_ACCESS_TOKEN';

// Insert survey ID here
$surveyid = 'YOUR_SURVEYID';
// The ID to be searched for 
$answerid = "2";

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

$ch = curl_init($apiUrl);

// Configure cURL options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ' . $accessToken,
));

// Carry out enquiry
$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);

?>
Example: All results of a poll where answer text X was given
PHP
<?php

// All results of a poll where answer text X was given
// getAllResultsWithAnswerTextX.php
// v1.0.1

// Insert access token here
$accessToken = 'YOUR_ACCESS_TOKEN';

// Insert survey ID here
$surveyid = 'YOUR_SURVEYID';
// The text to be searched for a text question
$answertext = "YOUR_TEXT";

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

$ch = curl_init($apiUrl);

// Configure cURL options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Authorization: Bearer ' . $accessToken,
));

// Carry out enquiry
$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);

?>

Ready to start? Create great surveys now!