Pull event engagement data

The Pigeonhole Live API allows you to easily integrate your analytics platform with Pigeonhole Live. With the API, you can get detailed interaction data for your event. Once retrieved, you can process it and feed it directly into your analytics platform.

Prerequisites

API Key (this will be assigned to the variable $API_KEY in this guide)

Objectives

Using pagination and filters
Listing votes on a Q&A session
Listing answer ratings on a Q&A session
Listing answers on a Poll Word Cloud session

Step 1. Using pagination and filters

The Pigeonhole Live API make use of a cursor based pagination strategy, providing you with greater flexibility when querying data. In every request, you may specify the optional cursor and count query parameters. The cursor field specifies the index to start querying from, and count specifies how many items to be queried.

To obtain the cursor for a query, make an initial request, for example to query for Sessions in a Pigeonhole:

curl -X GET https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/sessions \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

In the response, a links field and meta field is included, which contains details about the pagination, such as the cursor for the next page (meta.nextCursor).

{
  "data": [
    ...
  ],
  "links": {
    "next": "https://api.pigeonholelive.com/v2/pigeonholes/1/sessions?cursor=Y3Vyc29yXzEyMTc="
  },
  "meta": {
    "perPage": 30,
    "nextCursor": "Y3Vyc29yXzEyMTc=",
    "hasMore": true
  }
}

note

Some parts have been omitted for brevity

To query for the next page, you could query either the URL provided under links.next:

curl -X GET https://api.pigeonholelive.com/v2/pigeonholes/1/sessions?cursor=Y3Vyc29yXzEyMTc= \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

Or you could take the meta.nextCursor field and add it to the URL manually.

caution

If a next page does not exist, then meta.hasMore will be false, and links.next and meta.nextCursor will both be null.

To filter data in your query, you may specify a filter query parameter. The filters for each endpoint are available in the documentation here. In the example above, one of the filters available is startsBefore, which filters our Sessions that start before the date provided.

curl -X GET https://api.pigeonholelive.com/v2/pigeonholes/1/sessions?cursor=Y3Vyc29yXzEyMTc=&filter[startsBefore]=2020-01-01T09:00:00+08:00 \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

Completed Objective

Using pagination and filters

Step 2. Listing votes on a Q&A session

In a Q&A session, your audience is able to post questions from the Audience Web App, and upvote other questions posted. In your post event analytics, you can utilize this data to understand how your event went and the top concerns your audience might have.

As the endpoint to list votes for a Q&A session is scoped to a Pigeonhole, you need to use the sessionId filter:

curl -X GET https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/votes?filter[sessionId]=1 \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

This will return a list, where every element is a vote for a question under the session:

{
  "data": [
    {
      "attendeeId": 1,
      "createdAt": "2022-09-08T08:40:40Z",
      "session": {
        "id": 1,
        "name": "This is a session name",
        "type": "qna"
      },
      "question": {
        "id": 1,
        "content": "When was Pigeonhole Live founded?",
        "status": "approved"
      }
    }
  ],
  "links": {
    "next": null
  },
  "meta": {
    "perPage": 30,
    "nextCursor": null,
    "hasMore": false
  }
}

In addition, by specifying the questionId filer, you are able to retrieve all the votes for a particular question that you are interested in:

curl -X GET https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/votes?filter[sessionId]=1&filter[questionId]=1 \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

In your analytics platform, you can use this data to generate reports or dashboards for analytics such as number of votes or most voted question.

Completed Objective

Listing votes on a Q&A session

During a Q&A session, your audience can rate how well the question was answered. In your post event analytics, you could use this data to determine which questions require further elaboration or follow up actions.

Similarly, the endpoint is scoped to a Pigeonhole, and a sessionId filter needs to be specified:

curl -X GET https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/answer_ratings?filter[sessionId]=1 \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

This will return a list, where every element contains an answer rating, along with other details such as the question and session it is for:

{
  "data": [
    {
      "attendeeId": 1,
      "createdAt": "2022-09-09T04:48:13Z",
      "session": {
        "id": 1,
        "name": "This is a session name",
        "type": "qna"
      },
      "question": {
        "id": 1,
        "content": "This is an example question"
      },
      "answerRating": {
        "id": 1,
        "rate": 3
      }
    }
  ],
  "links": {
    "next": null
  },
  "meta": {
    "perPage": 30,
    "nextCursor": null,
    "hasMore": false
  }
}

A questionId filter can be specified to view all ratings for one question:

curl -X GET https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/answer_ratings?filter[sessionId]=1&filter[questionId]=1 \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

You can also make use of other filtering capabilities listed here, for example ratingBetween to get the count of ratings between a range:

curl -X GET https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/answer_ratings?filter[sessionId]=1&filter[ratingBetween]=2,4 \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

Completed Objective

Listing answer ratings on a Q&A session

Step 3. Listing answers on a Poll Word Cloud session

Utilizing Poll Word Word Clouds can improve your audience engagement , and gain insights. With the Pigeonhole Live API, you can pull Word Cloud data directly and feed it into your analytics platform, allowing you to build other forms of visualizations with it, such as a tree map.

Similarly, this endpoint is scoped to a Pigeonhole, and a sessionId filter needs to be specified:

curl -X GET https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/answers?filter[sessionId]=1 \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

This will return a list, where every element contains an answer, along with other details such as the session it is for:

{
  "data": [
    {
      "attendeeId": 1,
      "createdAt": "2022-09-09T04:48:13Z",
      "session": {
        "id": 1,
        "name": "This is a session name",
        "type": "poll_word_cloud"
      },
      "answer": {
        "id": 1,
        "content": "This is an example answer",
        "status": "approved"
      }
    }
  ],
  "links": {
    "next": null
  },
  "meta": {
    "perPage": 30,
    "nextCursor": null,
    "hasMore": false
  }
}

A status filter can be specified to narrow down your query, for example returning only approved answers:

curl -X GET https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/answers?filter[sessionId]=1&filter[status]=approved \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

Completed Objective

Listing answers on a Poll Word Cloud session

Prerequisites

Objectives

Step 1. Using pagination and filters​

note

caution

Completed Objective

Step 2. Listing votes on a Q&A session​

Completed Objective

Completed Objective

Step 3. Listing answers on a Poll Word Cloud session​

Completed Objective

Step 1. Using pagination and filters

Step 2. Listing votes on a Q&A session

Step 3. Listing answers on a Poll Word Cloud session