Retrieving Survey Results

Retrieve survey results using the Poll REST API.

Overview

This guide explains how to retrieve survey results using the Poll REST API.

📘

Note

In the API reference and developer documentation, surveys are referred to as polls.

In this guide, we retrieve the following resources through the Poll REST API:

  • Polls: A poll is a template of a survey form that a survey creator sends out to recipients to collect the desired information for specific Fact Sheets. Each poll has a unique ID.
  • Poll runs: A poll run is an operation of sending a specific version of a survey to recipients. Each poll run has a unique ID.
  • Poll results: A poll result stores the answers of survey recipients for a specific Fact Sheet. Each Fact Sheet included in a poll run generates a poll result with a unique ID.

Before You Start

Before you retrieve survey results, ensure that you have an API token and know how to authenticate to LeanIX APIs. For more information, see Authentication to LeanIX Services.

Step 1: Get the Poll ID

First, let's get the ID of the poll for which you want to retrieve results. To retrieve all polls, make a GET request to the following endpoint:

https://{SUBDOMAIN}.leanix.net/services/poll/v2/polls

In the example request, we retrieve a poll by its title using the q query parameter.

Example request:

curl -X GET 
--header 'Accept: application/json' 
--header 'Authorization: Bearer {ACCESS_TOKEN}'
'https://{SUBDOMAIN}.leanix.net/services/poll/v2/polls?page=1&size=30&sort=creationDate-desc&q=Location'

Example response:

{
  "status": "OK",
  "type": "Poll",
  "errors": [],
  "total": 1,
  "data": [
    {
      "id": "0b62781b-4266-4020-g87h-4cacb7947ba8",
      "legacyId": null,
      "questionnaire": {...},
      "title": "Location",
      "language": "en",
      ...
    }
  ]
}

From the response, save the id of the desired poll.

Step 2: Get the Poll Run ID

Now that you have the id of the poll, retrieve all runs for this poll. To do that, make a GET request to the following endpoint:

https://{SUBDOMAIN}.leanix.net/services/poll/v2/polls/{id}/pollRuns

Example request:

curl -X GET 
--header 'Accept: application/json' 
--header 'Authorization: Bearer {ACCESS_TOKEN}'
'https://{SUBDOMAIN}.leanix.net/services/poll/v2/polls/0b62781b-4266-4020-g87h-4cacb7947ba8/pollRuns?page=1&size=500&sort=startTime-desc'

Example response:

{
  "status": "OK",
  "type": "PollRun",
  "errors": [],
  "total": 2,
  "data": [
    {
      "id": "ce6a4af8-7060-4adc-5ac8-2daa85efe616",
      "legacyId": null,
      "poll": {...},
      "status": "STARTED",
      "progress": null,
      "startTime": "2023-08-24T10:55:54.693671Z",
      ...
    },
    {
      "id": "c0735b3b-b032-4b0d-{...}-77f5e68b5210",
      "legacyId": null,
      "poll": {...},
      "status": "STARTED",
      "progress": null,
      "startTime": "2023-08-22T06:40:08.927306Z",
      ...
    }
  ]
}

From the response, save the id of the desired poll run.

Step 3: Get Poll Results

You can get poll results for:

Get Results for All Fact Sheets in a Poll Run

With the poll run ID, you can retrieve results for all Fact Sheets included in the poll run. To do that, make a GET request to the following endpoint:

https://{SUBDOMAIN}.leanix.net/services/poll/v2/pollRuns/{pollRunID}/pollResults

Example request:

curl -X GET 
--header 'Accept: application/json' 
--header 'Authorization: Bearer {ACCESS_TOKEN}'
'https://{SUBDOMAIN}.leanix.net/services/poll/v2/pollRuns/ce6a4af8-7060-4adc-5ac8-2daa85efe616/pollResults'

The response contains poll results for all Fact Sheets included in the poll run. Each result is associated with a specific Fact Sheet and has a unique ID.

Example response:

{
  "status": "OK",
  "type": "PollResultDTO",
  "errors": [],
  "total": 2,
  "data": [
    {
      "id": "10fd7951-1e44-4643-e6g4-ed5db8c44e29",
      "pollRunId": "ce6a4af8-7060-4adc-5ac8-2daa85efe616",
      "status": "DONE",
      "answers": [
        {
          "questionId": "cc2a3670-9d9d-5e41-6g4h-c579cdd89b1c",
          "answer": [
            "Users are based in Australia."
          ],
          ...
    {
      "id": "2dff1a8b-33b6-494c-b855-c8604045e333",
      "pollRunId": "ce6a4af8-7060-4adc-5ac8-2daa85efe616",
      "status": "DONE",
      "answers": [
        {
          "questionId": "cc2a3670-9d9d-5e41-6g4h-c579cdd89b1c",
          "answer": [
            "Users are based in Brazil."
          ],
          ...
    }

Get a Result for a Specific Fact Sheet in a Poll Run

You can retrieve a result for a specific Fact Sheet included in a poll run by the result ID. First, retrieve all results and save the id of the desired result from the response.

To retrieve a poll result by ID, make a GET request to the following endpoint:

https://{SUBDOMAIN}.leanix.net/services/poll/v2/pollResults/{pollResultID}

Example request:

curl -X GET 
--header 'Accept: application/json' 
--header 'Authorization: Bearer {ACCESS_TOKEN}'
'https://{SUBDOMAIN}.leanix.net/services/poll/v2/pollResults/10fd7951-1e44-{...}-ae7c-ed5db8c44e29'

Example response:

{
  "status": "OK",
  "type": "PollResultDTO",
  "errors": [],
  "total": 0,
  "data": {
    "id": "10fd7951-1e44-4643-e6g4-ed5db8c44e29",
    "pollRunId": "ce6a4af8-7060-4adc-5ac8-2daa85efe616",
    "status": "DONE",
    "answers": [
      {
        "questionId": "cc2a3670-9d9d-5e41-6g4h-c579cdd89b1c",
        "answer": [
          "Users are based in Australia."
        ],
        "comments": null,
        "lastModified": "2023-08-25T06:50:28.288193Z",
        "lastModifiedBy": "1cec1b72-d073-4bf1-4gh6-c80ba68e095b",
        "substitute": null,
        "jsonAnswer": null
      }
    ],
    "users": [...],
    "requestingUser": null,
    "sender": {...},
    "factSheet": {...}
  }
}