Skip to content
  • There are no suggestions because the search field is empty.

Step by Step Guide: Admins & IT - Hive Open API

.Category: Open API | Type: Step-by-step guide | Part 2 of 2 in : Open API

💡 New to this feature? To understand more about the User Data Uploader and how to prepare your file, see [Link to page

What you'll find in this guide:

  1. Part 1: Admin setup

  2. Part 2: Connecting to your BI tool - IT or Data analyst

  3. Available endpoints

  4. Troubleshooting

  5. Support


💡 The Open API is configured in two stages: an admin in Hive creates a service account and generates an API key, then an IT or data analyst connects that key to their BI tool.

Part 1: Admin setup

Step 1 - Create a service account

A service account is not a person — it has no password and cannot log into Hive. It's a named account your API key is attached to, so you can identify where requests are coming from and manage access cleanly.

  1. Go to Settings and select Service Accounts
  2. Click Create service account
  3. Give it a descriptive name — for example, PowerBI Dashboard or HR Analytics Team — and save

You can create multiple service accounts, one per tool or team. Each can have its own API keys with different permission sets.

Step 2 - Generate an API key
  1. From the Service Accounts page, click on the account you just created (or select Manage API keys)
  2. Click Create API key
  3. Select the permissions for this key — these control which data types it can access. If you're unsure, you can grant full access initially and restrict later
  4. Click Create, then copy the API key immediately and store it in a secure location

 

‼️Important: API keys are shown only once at creation. If you navigate away without copying it, you will need to generate a new one. Store your key in a password manager or secure vault before closing the window.

Once created, the key will be listed under the service account with details including who created it, its permissions, creation date, and expiry date. Keys expire after 90 days and each key is rate-limited to 200 requests per minute.

Part 2: Connecting to your BI tool - IT or Data analyst

This section is for the IT or data analyst completing the integration.

Step 1 - Open the API documentation

Before building any integration, use Hive's built-in API documentation to explore endpoints and test requests live in your browser.

  1. From the Service Accounts page, click View API docs
  1. Enter your tenant slug — this is the subdomain of your Hive URL (e.g. if your URL is yourcompany.hive.hr, your slug is yourcompany)
  2. Paste your API key into the Authentication field — the documentation will use it automatically for all test requests in that session

Note: If you refresh the browser, you will need to re-enter your tenant slug and API key. They are not saved between sessions.

Step 2 - Test your connection

Each endpoint in the documentation has a Test request button. Use this to check what data looks like before writing any integration code.

  1. A 200 status means the request was successful
  2. A 401 status means unauthorised — usually an incorrect or missing API key
Step 3 - Connect to Power BI
  1. In Power BI for example, select Get Data > From Web
  2. Paste the Hive endpoint URL (e.g. api.hive.hr/v1/heatmap/{survey_id})
  3. When prompted for authentication, select Web API or Advanced and enter your API key as an HTTP request header: Authorization: Bearer [Your_Key]
  4. Use Power Query to clean and shape the response — Hive returns flattened JSON to minimise transformation work
Step 4 - Build your first view

Once connected, use the Attributes endpoint first to retrieve segment IDs, which you'll need to filter data in all other endpoints. Then use the Surveys endpoint to retrieve survey IDs for pulling scores, metrics, and Key Drivers.

 

Available endpoints

#

Endpoint

What it returns

When to use it

1

List attributes & segments

All demographic attributes, segment IDs, and date buckets

Run first — IDs here are needed to filter all other requests

2

List surveys

Survey name, type, status, start/end date

Use to find the survey ID for other endpoints

3

List survey questions

All questions in a survey, with type and options

Use to identify question IDs for the statistics endpoint

4

Get question statistics

Response count, average score, distribution, favourable scores

Detailed per-question analysis

5

List metrics

Engagement Index, eNPS, average score, custom metrics

Headline metrics; filterable by segment or date

6

Get Key Drivers

Driver questions, influence scores, coefficients, action labels

Understanding what's driving (or hindering) engagement

7

Get heatmap data

Flat list of scores by question and segment

Building custom heatmap visualisations

8

Get response facets

Available segments, buckets, and demographic filter options

Check which filters exist before making filtered requests

9

List Open Door submissions

Anonymous feedback text, filterable by date and segment

Feeding qualitative data into sentiment or NLP tools

10

List Hive Fives

Peer-to-peer recognition events with recipient and sender attributes

Mapping recognition trends and cross-department collaboration

Monitoring with API Logs

Every request made through the Open API is logged and visible to any user with the Administrator of Integrations role.

  1. Go to Settings and select API Logs
  2. Each entry shows: the endpoint called, the API key used, the parameters passed, the response status, and a link to the response data

API Logs are useful for monitoring usage patterns and debugging if something isn't working as expected.

API Logs are useful for monitoring usage patterns and debugging if something isn't working as expected.

 

Troubleshooting Common Errors

Use this table to diagnose and resolve common issues when setting up or using the Hive platform Open API.

Issue

Likely cause

Category

Fix

401 Unauthorised

API key missing or incorrect

Auth
  1. Check the key is pasted correctly with no leading or trailing spaces
  2. Confirm the header format is: Authorization: Bearer [Your_Key]
  3. Re-enter the key in the API docs auth field — it is not saved between sessions
  4. Review the permissions assigned to the key in Service Accounts
  5. Grant access to the required data type, or generate a new key with full access temporarily to test
  6. You need the Administrator of Integrations role to manage keys
  7. API keys expire after 90 days. Set a calendar reminder when generating a new key to avoid unexpected outages.
  8. Null segment data is not a bug — it is the confidentiality threshold working as intended.
  9. The API docs page is stateless. You must re-enter your tenant slug and API key every session.

Can’t find the API key

Key was not copied at creation

API key

Keys are shown only once. If you navigated away without copying, generate a new key from the Service Accounts page. Store all new keys in a password manager immediately.

API key has stopped working

Key has expired

API key

Keys expire after 90 days. Check the expiry date on the Service Accounts page and generate a replacement. Update the key in all connected BI tools.

Requests failing after many calls

Rate limit hit

API key

Each key is limited to 200 requests per minute. Spread requests over time, or use a separate service account with its own key for high-volume integrations.

Endpoint returns no data or access denied

Key lacks permission for that data type

Permissions

  

Can’t access Service Accounts or API Logs

Missing admin role

Permissions

Only users with the Administrator of Integrations role can access Service Accounts, generate API keys, and view API Logs. Contact your Hive platform administrator to have this role assigned.

Tenant slug not accepted in API docs

Wrong slug entered

Setup

The slug is the subdomain of your Hive URL. If your URL is yourcompany.hive.hr, your slug is yourcompany — do not include hive.hr.

Slug and key not working after browser refresh

Session state lost

Setup

The API documentation does not save your tenant slug or key between sessions. Re-enter both each time you open or refresh the docs page.

Can’t connect in Power BI

Wrong auth method selected

Setup

In Power BI, select Get Data > From Web. When prompted for authentication, choose Web API or Advanced and add the key as an HTTP header: Authorization: Bearer [Your_Key].

Segment data returns null

Response count below confidentiality threshold

Data

The API returns null (not zero) when a segment has fewer responses than your organisation’s confidentiality threshold. This is by design. Check your threshold settings in the Hive platform.

Filtered requests return no results

Incorrect segment or survey IDs

Data

Run the Attributes endpoint first to retrieve segment IDs, then the Surveys endpoint for survey IDs. All filter parameters depend on IDs from these two endpoints.

Recognition text shows as null

Employee marked recognition as private

Data

When a Hive Five is marked private, the recognition text is returned as null. The metadata count is still returned. This is expected behaviour to protect employee privacy.

Unexpected results from Open Door endpoint

Expecting individual responses

Data

Open Door submissions are fully anonymised — no employee identifiers are ever returned. Individual-level data is not available through the API.

Integration behaviour is unexpected or unclear

Hard to debug without logs

Setup

Go to Settings > API Logs. Each entry shows the endpoint called, key used, parameters, response status, and a link to the response data. Use this to trace what each request returned.

Notes

  1. API keys expire after 90 days. Set a calendar reminder when generating a new key to avoid unexpected outages.
  2. Null segment data is not a bug — it is the confidentiality threshold working as intended.
  3. The API docs page is stateless. You must re-enter your tenant slug and API key every session.
  4. For further technical assistance, contact Hive support via the customer portal at help.hive.hr.

 

◀ Previous

Back to Open API Overview

  

End 

Back to contents
🎓 Other Useful Information

Require further technical assistance? Contact Our Support Team