&frankly data API API Reference

This API provides access to data points such as KPIs, Response rates and Result summaries for questions asked in &frankly, as well as supporting information that may be required (such as groups that exists, when questions have been scheduled, basic question information etc). Authentication to access this endpoint is handle by API tokens that can be generated from your &frankly account as an Administrator under Account and API tokens and should be passed as a value to the header "Authorization".

The OpenAPI/Swagger definition of this API is avalable here.

API Endpoint
https://data.api.andfrankly.com/v1
Contact: help@andfrankly.com
Schemes: https
Version: 0.6

Authentication

api_key

type
apiKey
name
Authorization
in
header

Groups

Groups

GET /groups

This method will retun a list of all currently active groups that exists in the &frankly account. Use this information to get more descriptive information about the groups returned in other requests, or to identify a specific group that you want to fetch data points for by finding its unique ID.

200 OK
Group

Successful operation

type
Group
Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": 3939,
    "externalId": "0006784",
    "name": "&frankly core team",
    "description": "Everyone in the &frankly team",
    "subgroups": [
      3938
    ]
  }
]

KPIs and KPI values

KPIs and KPI values

GET /kpis

This method fetches the definition of KPIs for which there ever has been a value created for in the account, their ID and description. The ID may later be used to fetch values for a given group and/or set of groups. Note that KPIs are generated for many &frankly standard packages, but can also be created for specific packages and/or a combination of packages.

200 OK
KPI

Successful operation

type
KPI
404 Not Found

No such KPI and/or group found

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "id": "P-102",
    "name": "1. Motivation Pulsing",
    "imageURL": "https://app.andfrankly.com/assets/packages/motivation.png"
  }
]
KPIs and KPI values

GET /kpis/{kpiId}/values

This method can be used to fetch KPI data points for a given group and/or org-tree. Provide a KPI identifier in the path, and group id as well as an optional time range (if omitted, the latest KPI values will be returned) and a structure of group/KPI values will be returned, either for the group selected or the group and all groups that reside beneath it in the &frankly group tree. To identify the groups returned, use the /group endpoint to also fetch group object definitions.

kpiId: string
in path

Id of KPI whos values should be returned

groupId: string
in query

Id of the group whos KPI values we should fetch

includeSubgroups: boolean
in query

Wether to return KPI values for all subgroups to this group together with the group itself (i.e. the full org-tree of results)

fromDate: string (date)
in query

Date range we should fetch KPIs from, must be used with to_date if provided. Should be of form 2021-04-09. If omitted will fetch latest values.

toDate: string (date)
in query

Date range we should fetch KPIs to, must be used with from_date if provided. Should be of form 2021-04-15. If omitted will fetch latest values.

200 OK
KPI-values

Successful operation

404 Not Found

No such KPI and/or group found

Response Content-Types: application/json
Response Example (200 OK) 
{
  "kpi": {
    "id": "P-102",
    "name": "1. Motivation Pulsing",
    "imageURL": "https://app.andfrankly.com/assets/packages/motivation.png"
  },
  "values": [
    {
      "groupId": 3939,
      "value": "0.67",
      "yearWeek": "202115",
      "date": "2021-04-09"
    }
  ]
}

Response rates

Response rates

GET /responserates/values

This method can be used to fetch response rate data points for a given group and/or org-tree. Provide a group id as well as an optional time range (if omitted, the latest response rate values will be returned) and a structure of group/response rate values will be returned, either for the group selected or the group and all groups that reside beneath it in the &frankly group tree. To identify the groups returned, use the /group endpoint to also fetch group object definitions. Response rate values represent the response rate for questions asked to everyone in the group, i.e. questions asked to specific individuals by virtue of other group memberships are not included in the group data point.

groupId: string
in query

Id of the group whos response rate values we should fetch

includeSubgroups: boolean
in query

Wether to return response rate values for all subgroups to this group together with the group itself (i.e. the full org-tree of results)

fromDate: string (date)
in query

Date range we should fetch response rates from, must be used with to_date if provided. Should be of form 2021-04-09. If omitted will fetch latest values.

toDate: string (date)
in query

Date range we should fetch response rates to, must be used with from_date if provided. Should be of form 2021-04-15. If omitted will fetch latest values.

200 OK
ResponseRate-values

Successful operation

type
ResponseRate-values
404 Not Found

No such group found

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "values": [
      {
        "groupId": 3939,
        "value": "0.67",
        "yearWeek": "202115",
        "date": "2021-04-09"
      }
    ]
  }
]

Questions and results

Questions and results

GET /results

This method can be used to fetch result data for a given group and/or org-tree. Provide a group id, a set of question ids as well as an optional time range (if omitted, results values from the last 5 weeks will be returned) and a structure of group/result data will be returned, either for the group selected or the group and all groups that reside beneath it in the &frankly group tree. To understand which questions have been asked to which groups, used the /askedquestions endpoint. To identify the groups returned, use the /group endpoint to also fetch group object definitions. Result data is structured differently depending on the question type, more details about the data structure per question type will be provided here shortly.

groupId: string
in query

Id of the group whos result data we should fetch

includeSubgroups: boolean
in query

Wether to return result data for all subgroups to this group together with the group itself (i.e. the full org-tree of results)

includeComments: boolean
in query

Wether to include comment provided to questions in the response

granularData: boolean
in query

Wether to return granular data (i.e. individual answers) where it is possible. Note that not all question types supports providing individual data points, for such questions this setting will fall back to non-granular data i.e. averages/summaries instead.

questionIds: string
in query

Comma separated list of question ids for which result data should be fetched. If omitted will fetch all questions asked for the chosen period.

fromDate: string (date)
in query

Date range we should fetch results data from, must be used with to_date if provided. Should be of form 2021-04-09. If omitted will fetch results from the last 5 weeks.

toDate: string (date)
in query

Date range we should fetch result data to, must be used with from_date if provided. Should be of form 2021-04-15. If omitted will fetch results from the last 5 weeks.

language: string
in query

Language that the results should be returned in. Must be a two letter ISO-639-1 code, for example 'en'. If the question is defined with the given language, results will be returned in this language - else it will fall back to the base definition of the question.

200 OK
Results-values

Successful operation

type
Results-values
404 Not Found

No such group found

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "questions": [
      {
        "id": 98,
        "question": "How do you feel about coming to work?",
        "type": 15
      }
    ],
    "values": [
      {
        "98": {
          "3939": {
            "1842": {
              "value": 0.882589
            }
          }
        }
      }
    ],
    "comments": [
      {
        "98": {
          "3939": {
            "1842": [
              "This is a comment"
            ]
          }
        }
      }
    ]
  }
]
Questions and results

GET /askedquestions

This method can be used to fetch the set of questions asked to a given group and/or org-tree. Provide a group id and an optional time range (if omitted, all questions asked the last 5 weekswill be returned) and a structure of group/question/time data will be returned, either for the group selected or the group and all groups that reside beneath it in the &frankly group tree. Based on this information, you may use the /results endpoint to query the actual result data using group/question ids.

groupId: string
in query

Id of the group whos result data we should fetch

includeSubgroups: boolean
in query

Wether to return result data for all subgroups to this group together with the group itself (i.e. the full org-tree of results)

fromDate: string (date)
in query

Date range we should fetch results data from, must be used with to_date if provided. Should be of form 2021-04-09. If omitted will fetch questions asked the last 5 weeks.

toDate: string (date)
in query

Date range we should fetch result data to, must be used with from_date if provided. Should be of form 2021-04-15. If omitted will fetch questions asked the last 5 weeks.

language: string
in query

Language that the question definitions should be returned in. Must be a two letter ISO-639-1 code, for example 'en'. If the question is defined with the given language, results will be returned in this language - else it will fall back to the base definition of the question.

200 OK
Askedquestions-values

Successful operation

type
Askedquestions-values
404 Not Found

No such group found

Response Content-Types: application/json
Response Example (200 OK) 
[
  {
    "questions": [
      {
        "id": 98,
        "question": "How do you feel about coming to work?",
        "type": 15
      }
    ],
    "askedquestions": [
      {
        "3939": {
          "1842": [
            13,
            97,
            98,
            144,
            155
          ]
        }
      }
    ]
  }
]

Schema Definitions

KPI: object

id: string
name: string
imageURL: string
Example
{
  "id": "P-102",
  "name": "1. Motivation Pulsing",
  "imageURL": "https://app.andfrankly.com/assets/packages/motivation.png"
}

KPI-value: object

groupId: integer

ID of the group for which this KPI value is for

value: number (double)

KPI value between 0.0 and 1.0, or null if no value could be calculated (e.g. too few answers)

yearWeek: string

Year and week that this value is for on format YYYY-WW

date: string (date)

Date of the monday of the week that this value is for on format YYYY-MM-DD

Example
{
  "groupId": 3939,
  "value": "0.67",
  "yearWeek": "202115",
  "date": "2021-04-09"
}

KPI-values: object

kpi: KPI
values: KPI-value
KPI-value
Example
{
  "kpi": {
    "id": "P-102",
    "name": "1. Motivation Pulsing",
    "imageURL": "https://app.andfrankly.com/assets/packages/motivation.png"
  },
  "values": [
    {
      "groupId": 3939,
      "value": "0.67",
      "yearWeek": "202115",
      "date": "2021-04-09"
    }
  ]
}

ResponseRate-value: object

groupId: integer

ID of the group for which this response rate value is for

value: number (double)

Response rate value between 0.0 and 1.0, or null if no value could be calculated (e.g. too few answers)

yearWeek: string

Year and week that this value is for on format YYYY-WW

date: string (date)

Date of the monday of the week that this value is for on format YYYY-MM-DD

Example
{
  "groupId": 3939,
  "value": "0.67",
  "yearWeek": "202115",
  "date": "2021-04-09"
}

ResponseRate-values: object

values: ResponseRate-value
ResponseRate-value
Example
{
  "values": [
    {
      "groupId": 3939,
      "value": "0.67",
      "yearWeek": "202115",
      "date": "2021-04-09"
    }
  ]
}

Results-values: object

questions: Question
Question
values: Result-value
Result-value
comments: Comments-value
Comments-value
Example
{
  "questions": [
    {
      "id": 98,
      "question": "How do you feel about coming to work?",
      "type": 15
    }
  ],
  "values": [
    {
      "98": {
        "3939": {
          "1842": {
            "value": 0.882589
          }
        }
      }
    }
  ],
  "comments": [
    {
      "98": {
        "3939": {
          "1842": [
            "This is a comment"
          ]
        }
      }
    }
  ]
}

Result-value: object

object

An associative array with a set of question ids, for each question id a set of group ids,for each group a set of yearweeks and for each year week a JSON data structure that contains answer data (different depending on question type, see above) for this question/group/point in time

Example
{
  "98": {
    "3939": {
      "1842": {
        "value": 0.882589
      }
    }
  }
}

Comments-value: object

object

An associative array with a set of question ids, for each question id a set of group ids,for each group a set of yearweeks and for each year week a list of the comments provided for this question/group/week. Note that comments 'aggregate' upwards, so comments shown for a Group A that is above Group B includes all comments from Group B also.

Example
{
  "98": {
    "3939": {
      "1842": [
        "This is a comment"
      ]
    }
  }
}

Askedquestions-values: object

questions: Question
Question
askedquestions: Askedquestion-value
Askedquestion-value
Example
{
  "questions": [
    {
      "id": 98,
      "question": "How do you feel about coming to work?",
      "type": 15
    }
  ],
  "askedquestions": [
    {
      "3939": {
        "1842": [
          13,
          97,
          98,
          144,
          155
        ]
      }
    }
  ]
}

Askedquestion-value: object

object

An associative array with a set of group ids, for each group id a set of yearweeks (YYWW) that questions have been asked, and for each yearweek a list of question ids that were asked this week.

Example
{
  "3939": {
    "1842": [
      13,
      97,
      98,
      144,
      155
    ]
  }
}

Question: object

id: integer

Unique identifier for question

question: string

The question title

type: integer

Enum identifier for the type of question, from the following list: TBD

Example
{
  "id": 98,
  "question": "How do you feel about coming to work?",
  "type": 15
}

Group: object

id: integer

&frankly unique identifier for the group

externalId: string

Customer chosen unique identifier for the group (if set)

name: string
description: string
subgroups: integer[]

List of all child groups that reside beneath this group in the hierarchy

integer
Example
{
  "id": 3939,
  "externalId": "0006784",
  "name": "&frankly core team",
  "description": "Everyone in the &frankly team",
  "subgroups": [
    3938
  ]
}
Documentation by Spectacle