Empuls v1 API

📄 Introduction

Empuls API is a simple way to access Empuls internal APIs without requiring the user to go through to the web interface. At its core for authentication empuls uses OAuth 2.0 which allows API clients to access protected resources on behalf of a user without requiring the user's credentials. This document describes the API and its usage.

🔖 How to use this collection

Use the EmpulsAPI v1 postman environment.
Enter base_url variable. This is usually the URL of the Empuls portal. ie. https://abc.xoxoday.com
Enter the credentials provided by empuls team in client_id, client_secret, refresh_token variables.
Enter the email of the user you want to use the services as in the as_user variable.
Save the environment using ctrl+s or cmd+s.
Run the Authentication/Company Access Token endpoint to generate access_token. This access_token will be automatically used in the Services APIs

Authentication

The Empuls OAuth authentication flow consists of the following steps:

The empuls internal team will generate and share the Client ID, Client Secret, and Refresh Token with the user.
Use the given credentials to fetch Access Token using the /chef/v1/oauth/token/company endpoint
Send the Access Token in the Authorization header as Bearer for all the Sevices API
Send the email of the person you want to access the resources in as_user header.

You must include Authorization and as_user request header in each request to the Empuls API.

Point to note :

The access token will be valid for 1 day
The refresh token will be valid for 60 days
Each time an Access token is generated, the Refresh token expiration date is extended 60 days from that time

In this collection, we store Access Token/Hash and other variables in the environment and automatically use them as necessary.

Authentication error response

If an API key is missing, malformed, or invalid, you will receive an HTTP 401 Unauthorized response code.

503 response

An HTTP 503 response from our servers indicates there is an unexpected spike in API access traffic. The server is usually operational within the next five minutes.

AuthorizationBearer TokenToken{{access_token}}

Authentication

This endpoint lets users generate Access Token to use for authentication

AuthorizationBearer TokenThis folder is using an authorization helper from the collection Empuls v1 API

POSTGet Company Access Token

Open Request{{base_url}}/chef/v1/oauth/token/company

Gets information about the authenticated user.

Bodyraw (json)json

{
    "client_id": "{{client_id}}",
    "client_secret":"{{client_secret}}",
    "refresh_token":"{{refresh_token}}",
    "grant_type":"refresh_token"
}

Services

Services Collection contains all the available services accessible via API

AuthorizationBearer TokenThis folder is using an authorization helper from the collection Empuls v1 API

Appreciation

AuthorizationBearer TokenThis folder is using an authorization helper from the collection Empuls v1 API

POSTSend Award

Open Request{{base_url}}/chef/api/sdk/award.mutation.sendAwardAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIRequest Headersas_user{{as_user}}Bodyraw (json)json

{
    "award_id":"id of the award",
    "recipients":["[email protected]","[email protected]"],
    "citation_message":"citation message for the award",
    "points": 0,
    "budget_id":"id of the budget from which the points will be deducted",
    "group_id":"id of the group where the feed will be posted"
}

POSTSend Appreciation

OpenRequest{{base_url}}/chef/api/sdk/award.mutation.sendAppreciationAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIRequest Headersas_user{{as_user}}Bodyraw (json)json

{
    "hashtag":"#AppreciationName",
    "recipients":["[email protected]","[email protected]"],
    "citation_message":"citation message for the award",
    "group_id":"id of the group where the feed will be posted"
}

Gifting

AuthorizationBearer TokenThis folder is using an authorization helper from collection Empuls v1 API

POSTSend Gift

Open Request{{base_url}}/chef/api/sdk/gift.mutation.sendGiftAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIRequest Headersas_user{{as_user}}Bodyraw (json)View Morejson

{
    "gift_id":"id of the gift",
    "recipients":["[email protected]","[email protected]"],
    "condition":"optional use instead of recipients. sending both will result in error",
    "points":0
}

Webview

AuthorizationBearer TokenThis folder is using an authorization helper from collection Empuls v1 API

GETWebview

Open Request{{base_url}}/chef/api/webview?authorization={{access_token}}&as_user={{as_user}}&landing_page=appreciation&timestamp={{timestamp}}&hash={{hash}}Query Paramsauthorization{{access_token}}as_user{{as_user}}landing_pageappreciationtimestamp{{timestamp}}hash{{hash}}

Reporting

AuthorizationBearer TokenThis folder is using an authorization helper from collection Empuls v1 API

POSTAward Reports

Open Request{{base_url}}/chef/api/sdk/admin_reports.query.award_queryAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "limit": 10,
    "offset": 0,
    "start_date": "2023-04-21",
    "end_date": "2020-05-21",
    "timezone": "+05:30",
    "sorting": "fdc:desc",
    "filters":"{}"
}

POSTBudget Reports

Open Request{{base_url}}/chef/api/sdk/admin_reports.query.budget_points_queryAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "limit": 10,
    "offset": 0,
    "start_date": "2023-04-21",
    "end_date": "2020-05-21",
    "timezone": "+05:30",
    "filters":"{}"
}

POSTBudget Transaction

Open Request{{base_url}}/chef/api/sdk/admin_reports.query.budget_transactions_queryAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "limit":10,
    "offset":0,
    "start_date":"2023-01-07",
    "end_date":"2020-02-06",
    "timezone":"+05:30",
    "filters":"{}"
}

POSTConversation Reports

Open Request{{base_url}}/chef/api/sdk/admin_reports.query.conversation_queryAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "limit": 10,
    "offset": 0,
    "start_date": "2023-01-07",
    "end_date": "2023-02-06",
    "timezone": "+05:30",
    "sorting": "cat:desc",
    "filters":"{}"
}

POSTCore Value Reports

Open Request{{base_url}}/chef/api/sdk/admin_reports.query.corevalue_queryAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "limit": 10,
    "offset": 0,
    "start_date": "2023-01-08",
    "end_date": "2023-02-07",
    "timezone": "+05:30",
    "filters":"{}"
}

POSTGift Reports

Open Request{{base_url}}/chef/api/sdk/admin_reports.query.gift_queryAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "limit": 10,
    "offset": 0,
    "start_date": "2023-01-08",
    "end_date": "2023-02-07",
    "timezone": "+05:30",
    "filters":"{}"
}

POSTLeaderboard Reports

Open Request{{base_url}}/chef/api/sdk/admin_reports.query.leaderboard_queryAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "limit": 10,
    "offset": 0,
    "start_date": "2023-01-08",
    "end_date": "2023-02-07",
    "timezone": "+05:30",
    "sorting": "fed:desc",
    "filters":"{}"
}

POSTLogin Reports

Open Request{{base_url}}/chef/api/sdk/admin_reports.query.engagement_queryAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "limit": 10,
    "offset": 0,
    "start_date": "2023-01-08",
    "end_date": "2023-02-07",
    "timezone": "+05:30",
    "filters":"{}"
}

POSTNomination Reports

Open Request{{base_url}}/chef/api/sdk/admin_reports.query.nomination_queryAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "limit": 10,
    "offset": 0,
    "start_date": "2023-01-08",
    "end_date": "2023-02-07",
    "timezone": "+05:30",
    "sorting": "days_since:asc",
    "filters":"{}"
}

POSTRedemption Reports

Open Request{{base_url}}/chef/api/sdk/admin_reports.query.redemption_queryAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "limit": 10,
    "offset": 0,
    "start_date": "2023-01-08",
    "end_date": "2023-02-07",
    "timezone": "+05:30",
    "sorting": "fdc_utc:desc",
    "filters":"{}"
}

POSTReward Point Expiry Reports

Open Request{{base_url}}/chef/api/sdk/admin_reports.query.point_expiry_queryAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

Copy

{
    "limit": 10,
    "offset": 0,
    "start_date": "2023-01-08",
    "end_date": "2023-02-07",
    "timezone": "+05:30",
    "sorting": "date_created:desc",
    "filters":"{}"
}

POSTSurvey Reports

Open Request{{base_url}}/chef/api/sdk/insightReport.query.getSurveyDataListAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "limit": 10,
    "offset": 0,
    "start_date": "2023-01-08",
    "end_date": "2023-02-07",
    "timezone": "+05:30",
    "filters":"{}"
}

UserProfile

AuthorizationBearer TokenThis folder is using an authorization helper from collection Empuls v1 API

POSTFetch User Profile

Open Request{{base_url}}/chef/api/sdk/profile.query.getProfileAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)View Morejson

{
    "fields": [
        "high_priority_actions",
        "survey_quiz_invites",
        "my_profile",
        "notifications",
        "awards_achievements_received",
        "award_approval_requests"
    ],
    "limit": 10,
    "offset": 0
}

Feeds

AuthorizationBearer TokenThis folder is using an authorization helper from collection Empuls v1 API

POSTFetch Feeds

Open Request{{base_url}}/chef/api/sdk/feed.query.getFeedAuthorizationBearer TokenThis request is using an authorization helper from collection Empuls v1 APIBodyraw (json)json

{
    "group_id":"1686164069300-ecbd6cd6-d061-40ad-b35d-1da72568262d",
    "type": ["appreciate","awards"],
    "fetch_pinned_posts_only": true,
    "limit": 10,
    "offset": 0
}

Keka

Security Related FAQs

🖥️ Empuls Software Development Kit