Why should we use the API feature?
Using an API allows you to automatically synchronize employees and your organizational structure, this is called organization API. Another API that you can use is our data API, which allows you to access data generated from the results in &frankly.
The data 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).
How does it work?
Authentication to access this endpoint is handled by API tokens that can be generated from your &frankly account as an Administrator, go to Account > API access to generate access tokens.
How can we benefit from it?
People and groups: Using the API as a way to automatically synchronize the users from your HR system to &frankly will simplify the user management and make it easier to keep user lists up to date. This will save you time and ensures you are GDPR compliant when using &frankly.
Results and data: Using the data API to access data points will allow you to:
- Build your own KPI dashboard to show the Engagement KPIs on screens in the office together with other data
- Build widgets for the intranet portal so you can show the latest &frankly response rate or KPI values on the intranet portal
- Import the data into your data warehouses/business intelligence platforms
- Build your own visualisations of KPI data over time, like building your own overview or KPI view
- Send out automated emails to all HR & Managers when there are new KPI values available for their groups
About data API (advanced):
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 exist, when questions have been scheduled, basic question information etc). Authentication to access this endpoint is handled 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 header.
About organization API (advanced):
This API endpoint provides means to automatically update users and groups in &frankly, and can be used to e.g. set up an automated synchronization between your HR system and &frankly. When using this API, we consider what you send to it as "master" and i.e. will make sure that the current state in &frankly reflects the state that you send. This is done by considering users and groups that are provided through this API as managed. For managed users and groups, we can restrict manual changes in the application (if desired), and we will also perform corrections to all managed users and groups automatically via updates through this API. This means for example if you send a list of users A,B and C through this API, and in the next update you send users A,B and D, then user B will be renamed to b, C will be removed and user D will be added, and similarly for groups. User E that was created manually/outside of this API will be left alone, as will manually created groups.
The intended use of this API is to allow companies to send a set of users and groups that should always exist in &frankly (removing users that have left the company, and creating new users that have joined) and maintaining an up to date org-structure - but still allow users to create own groups outside of the structured outside of the org-structure.
It is possible to use this API in three manners:
- a) Send a full list of users and org structure that is kept up to date in &frankly,
- b) Send only a list of users and org units, allowing an administrator to build the tree based on these units, or
- c) Send only users, allowing an administrator to build & maintain their own org structure.
When using this API it is important to take care that any users AND org units that are sent are sent with correct unique identifiers, as it is what is used to base changes on. For example, if an org unit with identifier 0000A and name 'Sales Department' is sent to us and later it is removed because there is a new org unit with identifier 0000B that is named 'Sales Department', we will remove the old org unit in &frankly and create a new one (because it has a new unique identifier), which also means all historic results for the previous org unit will be removed/no longer possible to see.