How to use the Participant Activity Report APIs

This page provides an overview of Klaxoon activities, including quizzes, surveys, memos, and adventures, as well as the types of questions available in each activity. It also explains how to access activity reports using the Klaxoon API, including details on participants and results.

Main concepts

Using Klaxoon API you can build integrations to collect participation and result reports for Klaxoon activities. This first section describes the Klaxoon activities and type of questions available within these activities.

Klaxoon Activities

Klaxoon activityDescription
QuizA Quiz can include up to 20 questions of different formats: single or multiple choice, fill in the blank, find the word, drag'n drop... 9 types of Quiz questions are available to be enhanced visually with photos or videos. With either a “free” or “question by question” mode participants must answer the question correctly in order to advance to the next one.
SurveyA Survey is a series of 1 to 20 questions that may be used to gauge participants' opinions, assess their level of knowledge or ask questions about a topic. 6 types of questions are available
MemoA Memo is a set of 1 to 300 pages, quiz questions, and survey questions used to present ideas, images, and videos. The purpose of the questions is to ensure that participants have understood information or to ask their opinion.
AdventureAn Adventure is a sequence of 1 to 10 steps enabling participants to explore content in a fun environment. Each step consists of one or more quiz questions (9 types available), which may be introduced by a contents page if required (text, videos, and images).
MissionA Mission is a sequence of 1 to 10 steps enabling participants to explore content independently in a fun environment. Each step consists of an activity – Quiz, Survey, or Memo.
SessionA Session is a collection of activities designed to encourage interactivity at your face-to-face or remote meetings. It can include Adventure, Board, Memo, Quiz and Survey.

Two main families of questions can be found into these Klaxoon activities :

  • Quiz questions : used in the Quiz, Adventure and Memo activities
  • Survey questions : used in the Survey and Memo activities

Quiz questions

Available in Quiz, Adventure and Memo activities.

Quizz question typeDescriptionExample
Single choiceParticipants select one answer from several options.Spot the odd one out.
Multiple choiceParticipants select several answers from several options.What are the safety instructions?
Drag'n drop image to textParticipants match an image (thumbnail) with a text.Find the product names
Drag'n drop image to imageParticipants match an image with another image.Match these brands and their founders.
Find the wordParticipants must enter a word or number in response to a question.How many ... ? / In what year ... ? / What is the name of ... ?
Fill the gapsParticipants must enter words to fill in the gaps.Enter the missing words.
CategorizeParticipants turn over images to find pairs.Match the images.
Sort into orderParticipants sort items into order.Sort the following from newest to oldest.

Survey questions

Available in Survey and Memo Activities.

Survey question typeDescriptionExample
Single choiceParticipants select one answer from several options.Yes/No?
Multiple choice questionParticipants select several answers from several options.Have you ever ... ?
CommentParticipants can enter any comments they wish (for open questions).What positive aspects do you recall?
RatingParticipants award a score out of 5. You can enable the option allowing them to add a comment.Score the item.
Sort into orderParticipants must sort items into pre-defined categories.Sort by order of preference.
CategorizeParticipants must sort items into pre-defined categories.Do you think these objectives should be achieved in the short or long term?

To access Activity Reports from your application or service using the APIs you need to :

  1. Register your application. See the Create an App section.
  2. Provide users with a simple "Connect to Klaxoon" button for your application to be granted with Activity access right of the user. This can be done implementing the OAuth 2 authorization protocol for a Klaxoon users to authorize your application to read activities data.

User permissions

A Klaxoon user with access to an activity can either be host or participant with different rights :

Hosts

  • List participants of the activity
  • Retrieve participants results

Participants

  • List participants of the activity
  • Retrieve their own participant's details and results

Activities

An activity in Klaxoon is either a Quiz, a Survey, a Memo and Adventure. These activities can be listed using the following endpoints. It will return activities where the user is participant (not blocked) or the author.

Once the authorization flow is in place and a user granted access to your application the list or a specific activity available for this user can be retrieve using the following endpoints :

For each activity you get access to the following object

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "title": "Klaxoon activity title",
  "description": "This is a Klaxoon activity",
  "accessCode": "ABCDEFG",
  "state": "draft",
  "author": {
    "id": "string"
  },
  "createdAt": "2024-02-20T16:51:14.482Z",
  "updatedAt": "2024-02-20T16:51:14.482Z"
}
Objects and AttributesDescription
idUnique identifier for the activity
titleTitle of the activity
descriptionShort description of the activity
accessCodeUnique access code use to join the activity in Klaxoon
stateCurrent activity state. Can be one of the following
draft, published or closed
authorAuthor of the activity

Participants

A participant is user who actually participated to your activity in Klaxoon.

For a given Klaxoon activity you can either retrieve participant details of the current user, a specific participant or access the full list of participants using the following endpoints.

For each participant you get access to the following object

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "J.D",
  "role": "host",
  "user": {
    "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
     "firstname": "John",
     "lastname": "Doe",
  	 "email": "[email protected]"
    }
}
Participant Object and AttributesDescription
idID of the participant. This ID is unique by Activity participation.
usernameUsername of the participant. Available if Join using a Nickname option is enabled on the activity.
roleRole of the participant in the activity. Can be one of the following host or participant
userThe user information of the participant (see user object details below)
User Object and AttributesDescription
idUnique ID of the user.
firstnameFirst name of the participant. Available only if the participant is connected to his Klaxoon account when he join the activity.
lastnameLast name of the participant. Available only if the participant is connected to his Klaxoon account when he join the activity.
emailEmail of the participant. Only available for the current user or for all participants if the API call made by the host of the activity.

Results

Results associated with an activity can be included in the response alongside the participant resource. To indicate that you want to include result data you must specify the 'include' parameter with the value result when you request the Participant API endpoints.

Quiz Results

By using the include result parameter the Quiz result will be return in the payload as follow

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "J.D",
  "role": "host",
  "user": {
    "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
     "firstname": "John",
     "lastname": "Doe",
  	 "email": "[email protected]"
  }, 
  "result": {
    "progression": 33.33,
    "score": 33.33,
    "successRate": 66.66,
    "replays": 0,
    "firstActionDate": "2020-07-24T09:00:00.000+0000",
    "lastActionDate": "2020-07-24T09:00:00.000+0000",
    "feedback": {
      "comment": "string",
      "rating": 5
    }
  }
}
Result Object and AttributesDescription
progressionPercentage of questions answered by the participant out of the total number of questions in the Quiz
scoreScore of the participant based on the whole Quiz (percentage)
successRateScore of the participant based only on the questions already answered (percentage)
replaysThe number of times the participant replayed the Quiz. The initial participation does not count as a Replay.
firstActionDateDate of the first question answered by the participant
lastActionDateDate of the last question answered by the participant
feedbackThe feedback left by the participant at the end of the Quiz (see feedback object details below)
Feedback Object and AttributesDescription
commentThe comment left by the participant at the end of the Quiz
ratingThe rating left by the participant at the end of the Quiz

Survey Results

By using the include result parameter the Survey result will be return in the payload as follow

	
{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "J.D",
  "role": "host",
  "user": {
    "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]"
  },
  "result": {
    "progression": 33.33,
    "answerRate": 33.33,
    "firstActionDate": "2020-07-24T09:00:00.000+0000",
    "lastActionDate": "2020-07-24T09:00:00.000+0000",
    "feedback": {
      "comment": "string",
      "rating": 5
    }
  }
}
Result Object and AttributesDescription
progressionPercentage of questions answered by the participant out of the total number of questions in the Survey
answerRatePercentage of questions really answered (versus skipped) out of the total number of questions in the Survey
firstActionDateDate of the first question answered by the participant
lastActionDateDate of the last question answered by the participant
feedbackThe feedback left by the participant at the end of the Survey (see feedback object details below)
Feedback Object and AttributesDescription
commentThe comment left by the participant at the end of the Survey
ratingThe rating left by the participant at the end of the Survey

Memo Results

By using the include result parameter the Memo result will be return in the payload as follow

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "J.D",
  "role": "host",
  "user": {
    "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]"
  },
  "result": {
    "progression": 33.33,
    "score": 33.33,
    "successRate": 33.33,
    "answerRate": 33.33,
    "duration": 12345,
    "firstActionDate": "2020-07-24T09:00:00.000+0000",
    "lastActionDate": "2020-07-24T09:00:00.000+0000",
    "feedback": {
      "comment": "string",
      "rating": 5
    }
  }
}
Result Object and AttributesDescription
progressionPercentage pages (questions or simple pages) read by the participant out of the total number of pages in the Memo
scoreScore of the participant based on the whole Memo (percentage)
successRateScore of the participant based only on the questions already answered (percentage)
answerRatePercentage of questions really answered (versus skipped) out of the total number of questions in the Memo
durationDuration in seconds the participant spent reading the Memo (the timer is paused if the tab containing the memo is not active)
firstActionDateDate of the first question answered or page read by the participant
lastActionDateDate of the last question answered or page read by the participant
feedback objectThe feedback left by the participant at the end of the Memo (see feedback object details below)
Feedback Object and AttributesDescription
commentThe comment left by the participant at the end of the Memo
ratingThe rating left by the participant at the end of the Memo

Adventure Results

By using the include result parameter the Adventure result will be return in the payload as follow

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "J.D",
  "role": "host",
  "user": {
    "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]"
  },
  "result": {
    "progression": 33.33,
    "points": 1000,
    "successRate": 33.33,
    "score": 33.33,
    "replays": 2,
    "firstActionDate": "2020-07-24T09:00:00.000+0000",
    "lastActionDate": "2020-07-24T09:00:00.000+0000",
    "feedback": {
      "comment": "string",
      "rating": 5
    }
  }
}
Result Object and AttributesDescription
progressionPercentage of questions answered by the participant out of the total number of questions in the Adventure
pointsTotal points earned by the participant
scoreScore of the participant based on the questions of the whole Adventure (percentage)
successRateScore of the participant based only on questions already answered (percentage)
replaysThe number of times the participant replayed the Adventure. The initial participation does not count as a Replay.
firstActionDateDate of the first question answered by the participant
lastActionDateDate of the last question answered by the participant
feedback objectThe feedback left by the participant at the end of the Adventure (see feedback object details below)
Feedback Object and AttributesDescription
commentThe comment left by the participant at the end of the Adventure
ratingThe rating left by the participant at the end of the Adventure

Mission Results

By using the include result parameter the Mission result will be return in the payload as follow

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "J.D",
  "role": "host",
  "user": {
    "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]"
  },
  "result": {
    "progression": 33.33,
    "points": 1000,
    "successRate": 33.33,
    "score": 33.33,
    "firstActionDate": "2020-07-24T09:00:00.000+0000",
    "lastActionDate": "2020-07-24T09:00:00.000+0000",
    "feedback": {
      "comment": "string",
      "rating": 5
    }
  }
}
Result Object and AttributesDescription
progressionPercentage of steps completed by the participant out of the total number of steps in the Mission
pointsTotal points earned by the participant
scoreScore of the participant based on the Quiz activity steps of the whole Mission (percentage)
successRateScore of the participant based only on the Quiz activity steps already completed (percentage)
firstActionDateDate of the first question answered or page read by the participant
lastActionDateDate of the last question answered or page read by the participant
feedback objectThe feedback left by the participant at the end of the Mission (see feedback object details below)
Feedback Object and AttributesDescription
commentThe comment left by the participant at the end of the Mission
ratingThe rating left by the participant at the end of the Mission

Session Results

By using the include result parameter the Session result will be return in the payload as follow

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "username": "J.D",
  "role": "host",
  "user": {
    "id": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyy",
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]"
  },
  "result": {
    "points": 1000,
    "score": 33.33,
    "firstActionDate": "2020-07-24T09:00:00.000+0000",
    "lastActionDate": "2020-07-24T09:00:00.000+0000",
    "feedback": {
      "comment": "string",
      "rating": 5
    }
  }
}
Result Object and AttributesDescription
pointsTotal points earned by the participant
scoreScore of the participant based on the launched Quiz and Adventure activities of the Session (percentage)
firstActionDateDate of the first question answered, timeline interaction or page read by the participant
lastActionDateDate of the last question answered, timeline interaction or page read by the participant
feedback objectThe feedback left by the participant at the end of the Session (see feedback object details below)
Feedback Object and AttributesDescription
commentThe comment left by the participant at the end of the Session
ratingThe rating left by the participant at the end of the Session