TABLE OF CONTENTS

• Create and authorize an Integration Application in ZenHR.
• Test API endpoints using Postman.
• Obtain and use Access Tokens and Refresh Tokens.
• Connect ZenHR APIs to Microsoft Power BI.
• Configure automatic token refresh in Power BI.
• Configure ZenHR API in Power BI

API Documentation: https://api-docs.zenhr.com/#intro

Create an Integration Application in ZenHR

Prerequisites

• Active ZenHR account.
• User must have Global Admin permissions.
• List of required API scopes/endpoints.

Steps:

1. Navigate to:
   https://app.zenhr.com/en/oauth/applications
2. Click New Application.
3. Enter the Application Name.

4. Set the Redirect URL:

   https://oauth.pstmn.io/v1/callback

5. Select:
   • Data Access Level: Company

6. Select the required scopes based on the endpoints that will be consumed.

   Example:

   read:branch
   read:employee
   read:document
   read:document_type

7. Submit the application.
8. Copy the generated:
   • Client ID (UID)
   • Client Secret
9. Click Authorize.
10. Log in and approve the application.
11. After authorization, the application credentials are ready for use.

2. Test API Endpoints Using Postman

Import ZenHR Collection

1. Open Postman.
2. Import the ZenHR API Collection using the "Run in Postman" button available in the API documentation.
3. Select the imported collection.

Configure OAuth 2.0 Authorization

1. Open the Authorization tab.

2. Select:

   OAuth 2.0

3. Set Callback URL:

   https://oauth.pstmn.io/v1/callback

4. Configure Environment Variables:

5. Enter:
   • Client ID
   • Client Secret
6. Enter required scopes.

Example:

read:branch read:employee read:document read:document_type

7. Click Get New Access Token.
8. Log in using a Global Admin account.
9. Approve the authorization request.
10. Postman will generate the Access Token.
11. Click Use Token.

Branch ID Configuration

Many endpoints require a Branch ID.

To locate the Branch ID:

1. Navigate to:

   System Preferences
   → Branch Setup
   → Edit Preferred Branch

2. The Branch ID is visible in the URL.

Example:

https://app.zenhr.com/branches/12345/edit

Branch ID:

6227

3. Access Token vs Refresh Token

ZenHR OAuth uses two tokens:

Because the Access Token expires every hour, it is recommended to use the Refresh Token to automatically generate new Access Tokens without requiring user interaction.

4. Obtaining a New Access Token Using Refresh Token

The following request can be used to generate a new Access Token.

Token Request

POST https://app.zenhr.com/oauth/token

Request Body:

grant_type=refresh_token
refresh_token=YOUR_REFRESH_TOKEN
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

The response will contain:

{
  "access_token": "xxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "xxxx"
}

5. Connecting ZenHR APIs to Power BI

Power BI can consume ZenHR API endpoints through the Web Connector.

There are two approaches:

Option 1: Hardcoded Token (Not Recommended)

A Bearer Token can be directly added to the API request.

Example:

let
    Source =
        Json.Document(
            Web.Contents(
                "https://app.zenhr.com/api/v3/branches",
                [
                    Headers=[
                        Authorization="Bearer ACCESS_TOKEN",
                        #"Content-Type"="application/json"
                    ]
                ]
            )
        )
in
    Source

Limitation

The token becomes visible within the Power BI file and must be manually updated after expiration.

Option 2: Automatic Token Refresh (Recommended)

This approach uses the Refresh Token to generate a new Access Token automatically whenever the report refreshes.

Step 1 – Generate Access Token

let
    TokenResponse =
        Json.Document(
            Web.Contents(
                "https://app.zenhr.com/oauth/token",
                [
                    Content = Text.ToBinary(
                        "grant_type=refresh_token" &
                        "&refresh_token=YOUR_REFRESH_TOKEN" &
                        "&client_id=YOUR_CLIENT_ID" &
                        "&client_secret=YOUR_CLIENT_SECRET"
                    ),
                    Headers = [
                        #"Content-Type" = "application/x-www-form-urlencoded"
                    ]
                ]
            )
        ),

    AccessToken = TokenResponse[access_token]
in
    AccessToken

Step 2 – Use Generated Access Token

let
    Source =
        Json.Document(
            Web.Contents(
                "https://app.zenhr.com/api/v3/branches",
                [
                    Headers = [
                        Authorization = "Bearer " & AccessToken,
                        #"Content-Type" = "application/json"
                    ]
                ]
            )
        )
in
    Source

7. Configure ZenHR API in Power BI

Step 1 – Open Power BI Desktop

1. Launch Microsoft Power BI Desktop.
2. Open a new or existing report.

Step 2 – Create a Blank Query

1. From the Home ribbon, click:

   Transform Data

2. The Power Query Editor will open.

3. Select:

   Home → New Source → Blank Query

4. A new query will appear in the Queries pane.

5. Right-click the query and select:

   Rename

6. Rename it to:

   ZenHR_API

Step 3 – Open Advanced Editor

1. Select the newly created query.

2. Click:

   Home → Advanced Editor

3. Remove the default code.
4. Paste the ZenHR API script.

Step 4 – Create a Query to Generate Access Token

Create a new Blank Query and rename it:

ZenHR_Token

Open the Advanced Editor and paste:

let
    TokenResponse =
        Json.Document(
            Web.Contents(
                "https://app.zenhr.com/oauth/token",
                [
                    Content =
                        Text.ToBinary(
                            "grant_type=refresh_token" &
                            "&refresh_token=YOUR_REFRESH_TOKEN" &
                            "&client_id=YOUR_CLIENT_ID" &
                            "&client_secret=YOUR_CLIENT_SECRET"
                        ),
                    Headers =
                        [
                            #"Content-Type" = "application/x-www-form-urlencoded"
                        ]
                ]
            )
        ),

    AccessToken = TokenResponse[access_token]

in
    AccessToken

Replace:

• YOUR_CLIENT_ID
• YOUR_CLIENT_SECRET
• YOUR_REFRESH_TOKEN

with the values obtained from ZenHR.

Click Done.

The query should return the generated Access Token.

Step 5 – Create a Query to Retrieve Data

Create another Blank Query and rename it:

Branches

Open the Advanced Editor and paste:

let
    AccessToken = ZenHR_Token,

    Source =
        Json.Document(
            Web.Contents(
                "https://app.zenhr.com/api/v3/branches",
                [
                    Headers =
                        [
                            Authorization = "Bearer " & AccessToken,
                            #"Content-Type" = "application/json"
                        ]
                ]
            )
        )

in
    Source

Click Done.

Power BI will call the endpoint and return the JSON response.

Step 6 – Configure Authentication

The first time the query runs, Power BI may ask for credentials.

Choose:

Anonymous

and click:

Connect

Why Anonymous?

Because authentication is already being handled inside the M code using the OAuth Bearer Token generated from the ZenHR Refresh Token.
No additional Power BI authentication is required.

Step 7 – Convert JSON Data into a Table

Depending on the endpoint, Power BI may display:

• Record
• List
• Table

If a Record is returned:

1. Click the Record value.

2. Select:

   To Table

3. Expand the resulting columns.

If a List is returned:

1. Select:

   To Table

2. Expand the columns.

Continue expanding until the desired fields are displayed.

Step 8 – Load Data into Power BI

Once the data is properly structured:

1. Click:

   Close & Apply

2. Power BI will load the data model.
3. Create reports, dashboards, and visualizations using the imported ZenHR data.

Step 9 – Refreshing Data

When the report refreshes:

1. Power BI executes the token query.
2. A new Access Token is generated using the Refresh Token.
3. The API endpoint is called using the new Access Token.
4. Updated data is retrieved automatically.

No manual token generation is required.

Example Architecture

Power BI
    │
    ▼
Refresh Token
    │
    ▼
ZenHR OAuth Server
    │
    ▼
New Access Token
    │
    ▼
ZenHR API Endpoint
    │
    ▼
JSON Response
    │
    ▼
Power BI Dataset

This setup ensures secure, automated, and scalable data extraction from ZenHR into Power BI.

Supported Endpoints

Clients may consume any endpoint that has been granted through the selected OAuth scopes.

For the complete list of endpoints and request/response examples, refer to:

https://api-docs.zenhr.com/#intro