Integrate into your platform

The Pigeonhole Live API allows you to integrate your platform seamlessly with Pigeonhole Live. With the API, your customers will be able to use Pigeonhole Live directly from your platform.

Prerequisites

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

Objectives

Adding your customer’s API Key to the platform
Creating a Pigeonhole
Fetching Pigeonholes
Inspecting a Pigeonhole
Creating a Session
Fetching insights

Step 1. Adding your customer’s API Key to the platform

When interfacing with the Pigeonhole Live API, your platform will need to provide an API Key. This API Key has access to all entities under the Workspace it belongs to. Your platform will need to obtain and store the customers API Key, and include it in requests sent to the Pigeonhole Live API. The implementation details depends on your platform requirements.

Completed Objective

Adding your customer's API Key to the platform

Step 2. Creating a Pigeonhole

To build a seamless experience for your customers, your platform can provide functionality to create a Pigeonhole. It can also link the Pigeonhole to a platform specific context. For example, ACME company provides an insights platform for events, and events created under the platform can have a corresponding Pigeonhole.

To create a Pigeonhole, you first need to have a subscription:

If the Workspace is a Personal workspace, you do not need a Subscription ID.
If the Workspace is a Team workspace, creating a Pigeonhole from the API requires one of the available Subscription plans under the workspace to be selected.

You can display the Subscriptions available in the workspace to your customer, and then subsequently retrieve the corresponding Subscription ID. To retrieve the list of Subscriptions, make the following API call:

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

You will get a response containing all available Subscriptions:

{
  "data": [
    {
      "id": 1,
      "name": "ACME Enterprise Team Plan",
      "startDate": "2017-04-05T00:00:00+08:00",
      "endDate": "2022-12-31T00:00:00+08:00",
      "timezone": "Asia/Singapore"
    }
  ],
  "links": {
    "next": null
  },
  "meta": {
    "perPage": 30,
    "nextCursor": null,
    "hasMore": false
  }
}

The list under data displays all Subscriptions available to the Workspace. Keep in mind the Subscription ID shown (data[0].id), which will be required for creating a Pigeonhole.

Now that we have the Subscription ID, we proceed with creating our Pigeonhole. The required fields are listed here.

Make the following API call:

curl -X POST https://api.pigeonholelive.com/v2/pigeonholes \
  -d '{"name": "My First Event", "startDate": "2022-08-24", "endDate": "2022-08-25", "timezone": "Asia/Singapore"}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

caution

Remember to include the Subscription ID if a Team Workspace is used.

You will get a response containing the Pigeonhole that has been created:

{
  "data": {
    "id": 1,
    "name": "My First Event",
    "description": "Welcome! All available sessions are shown below.",
    "passcode": "DNAPMD",
    "startDate": "2022-08-24",
    "endDate": "2022-08-25",
    "status": "new",
    "timezone": "Asia/Singapore",
    "attendeeProfiles": true,
    "registrants": false,
    "attendeeCodeRequired": false,
    "links": {
      ...
    }
  }
}

note

Some parts have been omitted for brevity

A Pigeonhole is now created under your customers Workspace, and you can use the Pigeonhole ID to link it to other features your platform provides.

Completed Objective

Creating a Pigeonhole

Step 3. Fetching Pigeonholes

You are also able to retrieve existing Pigeonholes and display them in your platform.

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

The response will include brief details of each Pigeonhole under the Workspace:

{
  "data": [
    {
      "id": 1,
      "name": "This is a Pigeonhole!",
      "description": "Welcome! All available sessions are shown below. Tap on any to enter and start engaging.",
      "passcode": "ABCDEF",
      "startDate": "2019-11-26",
      "endDate": "2019-11-29",
      "status": "ended",
      "timezone": "Asia/Singapore",
      "attendeeProfiles": true,
      "registrants": false,
      "attendeeCodeRequired": false,
      "links": {
        ...
      }
    }
  ],
  "links": {
    "next": "https://api.pigeonholelive.com/v2/pigeonholes?cursor=Y3Vyc29yXzI1NzQ4MQ=="
  },
  "meta": {
    "perPage": 30,
    "nextCursor": "Y3Vyc29yXzI1NzQ4MQ==",
    "hasMore": true
  }
}

Completed Objective

Fetching Pigeonholes

Step 4. Inspecting a Pigeonhole

Sometimes, your platform would need to view additional details about a Pigeonhole that is not available in the response provided above. To view more details about a Pigeonhole (or any other entity), you can inspect it:

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

The response will include additional details about the Pigeonhole, such as expectedParticipants:

{
  "data": {
    "id": 31,
    "name": "My First Event",
    "expectedParticipants": 10000,
    ...
    "links": {
      ...
    }
  }
}

note

Some parts have been omitted for brevity

View the full list of fields returned here

Completed Objective

Inspecting a Pigeonhole

Step 5. Creating a Session

After a Pigeonhole is created, the next step is to populate it with sessions for your event. There are many types of sessions that can be created through the API, and many customization options available. Read here for more.

For this example, we will create a Q&A Session, which requires the name, startDate and endDate fields.

To create a session, make the following API call:

curl -X POST https://api.pigeonholelive.com/v2/pigeonholes/$PIGEONHOLE_ID/sessions \
  -d '{"name": "My First Event", "type": "qna", "startDate": "2022-08-24T04:14:34Z", "endDate": "2022-08-24T05:14:34Z"}' \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json"

caution

Keep in mind to fill in all required fields for the session type when creating your session.

You will get a response containing the Session that has been created:

{
  "data": {
    "id": 1,
    "name": "My First Event",
    "type": "qna",
    "description": "",
    "redirectAttendeesTo": "none",
    "location": "",
    "startDate": "2022-08-24T12:14:34+08:00",
    "endDate": "2022-08-24T13:14:34+08:00",
    "createdAt": "2022-08-04T04:20:08Z",
    "sessionLabel": "",
    "buttonText": "",
    "anonymousResponses": true,
    "questionFiltering": false,
    "comments": true,
    "commentFiltering": false,
    "answers": false,
    "answerRatings": true,
    "adminCollaboration": false,
    "hideOtherAttendeesQuestions": false,
    "questionVotes": true,
    "questionsAvailableAfterEnd": true,
    "tagsRequired": false,
    "logoPosition": "header",
    "tags": "",
    "displayQuestionsBy": "top_voted",
    "externalVideoReactions": false,
    "links": {
      ...
    }
  }
}

note

Some parts have been omitted for brevity

A Session is now created under the Pigeonhole, and you can now fetch detailed insights for it.

Completed Objective

Creating a Session

Step 6. Fetching insights

Your platform can fetch insights for a Session and combine it with related data, to display to the user in a cohesive manner. For example, your platform may handle in person event attendance, and provide an integration to Pigeonhole Live for online Q&A and audience engagement. At the end of the session, you would be able to provide insights on attendance and audience engagement levels directly from your platform. This section will go through how to fetch insights for Q&As. View the full list of insights available here.

To get the questions posted for a Q&A:

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

As this endpoint is scoped at the Pigeonhole level, you will get all questions in that Pigeonhole:

{
  "data": [
    {
      "attendeeId": 1,
      "createdAt": "2022-08-23T02:32:34Z",
      "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
  }
}

To get questions for a session, the Pigeonhole Live API supports filtering as a query parameter:

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

Completed Objective

Fetching insights

Prerequisites

Objectives

Step 1. Adding your customer’s API Key to the platform​

Completed Objective

Step 2. Creating a Pigeonhole​

caution

note

Completed Objective

Step 3. Fetching Pigeonholes​

Completed Objective

Step 4. Inspecting a Pigeonhole​

note

Completed Objective

Step 5. Creating a Session​

caution

note

Completed Objective

Step 6. Fetching insights​

Completed Objective

Step 1. Adding your customer’s API Key to the platform

Step 2. Creating a Pigeonhole

Step 3. Fetching Pigeonholes

Step 4. Inspecting a Pigeonhole

Step 5. Creating a Session

Step 6. Fetching insights