All Collections
Resources
🖥️ Empuls Software Development Kit
🖥️ Empuls Software Development Kit

Integration Guide for Intranet Site

Updated over a week ago

Business Objective

To build a white-labelled rewards solution within the intranet to address the branding needs of the organization.

Goals

Build a white-labelled rewards and recognition solution that can be adopted by organizations via integrations.

Non-Goals

Additional Empuls features like Leaderboard, Surveys, Groups, etc are not in scope for this program.

Assumptions

The white-labeled product solution is targeted towards the end-users i.e. employee and manager persona. Admin functions like HR associated with managing the reward program will access the Empuls web app to configure the rewards program.

Features Index

Here are the features covered as part of this documentation. Click on the respective link to view the sample request and response.

1. Authentication & Authorisation

The customer will be able to initiate the integration using the Client ID, Client Secret, and Refresh Token. These inputs will be provided by the Empuls team upon request.

Few things to note while setting up this integration

  • The client is required to generate the access token using the Client ID, Client Secret, and Refresh token provided. This access token will be valid for 1 day.

  • The refresh token gets updated every time a new access token is generated. The refresh token will be valid for 60 days.

Here are the request and the response templates for the Empuls OAuth authentication flow

Request:

curl -X POST https://{{subdomain}}.xoxoday.com/chef/v1/OAuth/token/company -d '{ "grant_type":"refresh_token", "refresh_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "client_id":"xxxxxxxxxxxxxxxxxxxxxxxxxxx", "client_secret":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }'

Response in case of a valid request:

{ "access_token": "xoxoc-eysdkhsdbjbdfsNvbnRlbnQiOnsiaXNzdWVkRm9yIjoiRnJlc2h3b3JrcyIsInNjb3BlIjoiIiwiaXNzdWVkQXQiOjE1NTk4MDQ1NTAxMzYsImV4cGlyZXNBdCI6IjIwMTktMDctMDZUMDc6MDI6MzAuMTM2WiIsInRva2VuX3R5cGUiOiJDT01QQU5ZIn0sImFfdCI6ImY3ZWM1MWMyYmE0ZGNmNzY2ZWE0ZDExMTI3ZjEzZjQzZjAwZmNhsdjhfbsfdjblfs", "token_type": "bearer", "expires_in": 86400, //seconds "refresh_token": "sdff064be187f42e9238122ef9d7a985c8800dff3752" }

Error Response:

{ "error": "invalid_request", "error_description": "missing/invalid parameters authorization header" }

The client can now use the access token to access the Empuls API and Webview on behalf of the user. The authorization for web-view generation and API requests are provided in the next section.

Authorization for Web view

Here is the request preview for the authorization request format for the generation of a web view for Empuls features.

Request URL:

https://{{subdomain}}.xoxoday.com/chef/api/webview?authorization={{access_token}}&as_user={{as_user}}&timestamp={{timestamp}}&hash={{hash}}&&landing_page={{landing_page}}

Query Parameter Key

Value

Comments

authorization

Access Token

Required. Token obtained from Authentication For eg. xoxoc-eysdkhsdbjbdfsxxxx

as_user

URL encoded email id of the user who is performing the action

Required. For eg:[email protected]

timestamp

Epoch unix timestamp in milliseconds

Required. The timestamp of the request must be not older than 5 minutes. For eg. 1679556062000

hash

This is the SHA512 hash generated from the following String.as_user

timestamp

landing_page

This value will determine the page to be loaded on the web view. Supported values - appreciation, redemption, home

Optional. If not mentioned home will be the landing page by default.

Authorization for API Requests

The client can access the protected resources on the server via API’s by following the request format provided.

curl -X POST 'https://{{subdomain}}.xoxoday.com/chef/api/award.mutation.sendAward' \\ -H 'Authorization: Bearer <Token>' \\ -H 'as_user: [email protected]' \\ -H 'Content-Type: application/json' \\ -d '{ .... .... .... .... }'

Few points to note:

  • The Get requests may not require an access token whereas POST requests pertaining to write functions may require a taken with a specific scope.

  • The client also needs to share the end-user email id as registered on Empuls in the as_user request header to call the API on behalf of a particular user.

2. Appreciate

The users can send appreciations, and awards or submit nominations using the Appreciate feature on Empuls. The same capability can be made available within the client systems by means of webview.

Here is the video preview of the web view of Appreciate feature

Request URL for Appreciate Web-view:

https://{{subdomain}}.xoxoday.com/chef/api/webview?authorization={{access_token}}&as_user={{as_user}}&timestamp={{timestamp}}&hash={{hash}}&&landing_page=appreciation

Refer Authorization for Web-view section for more details.

Appreciate API Request

Appreciate API allows you to automate rewarding end users for various business use cases. This option best suits performance management systems that automatically reward employees for achieving their quarterly/annual goals.

  • Request Message

    curl -X POST 'https://{{subdomain}}.xoxoday.com/chef/api/award.mutation.sendAward' \\ -H 'Authorization: Bearer <Token>' \\ -H 'as_user: [email protected]' \\ -H 'Content-Type: application/json' \\ -d '{ "award_id": "xxxxxxxxxxxxxxxxxx", "recipients": ["[email protected]","[email protected]"], "budget_id": "xxxxxxxx", "citation_message": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "points": 10, "group_id": "xxxxxxxxxxxxxxxxxxxxxx" }'

  • Header

  • Payload

  • Response

    { "data": { "sendAward": { "success": 1, "status": 201, "message": "Award sent successfully", "appreciation_id": "xxxxx0542fxxxxxad4050", "error_code": null } } }

3. Send Gifts In Testing

Send Gifts API allows you to automate gifting end users for various business use cases. This option is best suited for referral, learning management systems, and other business applications that intend to incentive employees with points for actions that are not associated with their performance at their job. Here is a video walkthrough of the gifts feature on Empuls.

P.S: Unlike Awards, Gifts do not generate any feed messages on townhall or any groups.

  • API Request

    curl -X POST 'https://{{subdomain}}.xoxoday.com/chef/api/award.mutation.sendGift' \\ -H 'Authorization: Bearer <Token>' \\ -H 'as_user: [email protected]' \\ -H 'Content-Type: application/json' \\ -d '{ "gift_id": "xxxxxxxxxxxxxxxxxx", "recipients": ["[email protected]","[email protected]"] }'

  • Header

  • Payload

Response

{ "data": { "sendGift": { "success": 1, "status": 201, "message": "Gift sent successfully", "gift_transaction_id": "xxxxx0542fxxxxxad4050", "error_code": null } } }

4. Redeem Reward Points

The users can redeem the reward points they have accumulated in their Empuls account on Empuls Store. The client system can allow users with points to open the Empuls store on a web view to allow them to purchase gift cards using the points

Here is the video preview of the web view of the redemption feature:

  • Request URL for Redemption Web-view

    https://{{subdomain}}.xoxoday.com/chef/api/webview?authorization={{access_token}}&as_user={{as_user}}&timestamp={{timestamp}}&hash={{hash}}&&landing_page=home

    Refer Authorization for Web-view section for more details.

5. Home

The home page is a common landing page that allows users to do everything that the Empuls web app offers. This includes the option to give awards, redeem points, view updates of your organization, and more.

Here is the video preview of the web view of the home page

  • Request URL for Home Page Web-view:

    https://{{subdomain}}.xoxoday.com/chef/api/webview?authorization={{access_token}}&as_user={{as_user}}&timestamp={{timestamp}}&hash={{hash}}&&landing_page=home

6 Reports In Testing

Reports API shares the various details captured as part of the Empuls reports. This will span across features and provides you insights about different aspects of the rewards program on Empuls.

6.1 Fetch Awards Issued API

This API allows you to fetch the list of all awards issued within a given time period.

  • API Request

    curl --location '<https://empulsaccounts.xoxoday.com/chef/v1/oauth/api/admin_reports.query.award_query>' \\ -H 'Authorization: Bearer <Token>' \\ -H 'as_user: [email protected]' \\ -H 'Content-Type: application/json' \\ -d '{ "limit": 10, "offset": 0, "start_date": "2021-04-21", "end_date": "2021-05-21", "timezone": "+05:30", "sorting": "fdc:desc" }'

  • Header

  • Payload

  • Response

    {
    "data": {
    "fetchAwardInfo": {
    "success": "1",
    "res": [
    {
    "approval_status": "Approved",
    "award_name": "Nomination Indi + team",
    "budget_name": "Personal Budget",
    "fdc": "2021-05-17 07:34:24 PM",
    "budget_owner": {
    "success": 1,
    "data": [
    {
    "employee_first_name": "Demo10",
    "employee_middle_name": null,
    "employee_last_name": "",
    "employee_email": null,
    "employee_id": null
    }
    ]
    },
    "nominator_details": {
    "success": 1,
    "data": [
    {
    "employee_first_name": "CHIRAG1",
    "employee_middle_name": "",
    "employee_last_name": "SHARMA",
    "employee_email": "[email protected]",
    "employee_id": "Demo901"
    }
    ]
    },
    "nominee_details": {
    "success": 1,
    "data": [
    {
    "employee_first_name": "Chirag DEMO",
    "employee_middle_name": "",
    "employee_last_name": "12",
    "employee_email": "[email protected]",
    "employee_id": "Demo903"
    }
    ]
    },
    "approver_details": {
    "success": 1,
    "data": [
    {
    "employee_first_name": "CHIRAG1",
    "employee_middle_name": "",
    "employee_last_name": "SHARMA",
    "employee_email": "[email protected]",
    "employee_id": "Demo901"
    }
    ]
    },
    "total_points": "1",
    "fdm": "2021-05-17 07:34:51 PM",
    "citation": "Hello Us",
    "image_url": "<https://imagestore-002.xoxoday.com/image/clients/10479500000000000/award/1612935048219.jpeg?versionId=ElO687ViMOPRsbKEcum8tx6ViT_JjGIu>"
    }
    ],
    "total": 1
    }
    }
    }

    1. Approved: if the award is issued,

    2. Revoked: If the award issued was taken back | | budget_owner | Owner of the budget used to issue this award | | | nominator_details | User who nominated the recipients for this award | | | nominee_details | Recipients of the award | Can consist of 1 or more users. | | approver_details | Details of the user who reviewed this nomination at the final level | Blank in case of spot / Instant awards. | | citation | Recognition message shared by the nominator for giving this award/ submitting the nomination | | | image_url | Recognition image published on Empuls feeds | | | error_code | null or one of the unique error identifier | String. Blank in case of a successful transaction. |

6.2 Fetch Core Values API

This API allows you to fetch the list of all non-monetary recognitions i.e. core values issued between a given time period.

  • API Request

    curl --location '<https://empulsaccounts.xoxoday.com/chef/v1/oauth/api/admin_reports.query.corevalue_query>' \\
    -H 'Authorization: Bearer <Token>' \\
    -H 'as_user: [email protected]' \\
    -H 'Content-Type: application/json' \\
    -d '{
    "limit":10,
    "offset":0,
    "start_date":"2023-04-25",
    "end_date":"2023-05-25",
    "timezone":"+05:30"
    "sorting": "fdc:desc"
    }'

  • Header

  • Payload

  • Response

    {
    "data": {
    "fetchCorevalue": {
    "success": 1,
    "status": 200,
    "res": [
    {
    "id": "1684945052973-1fe264b0-f24a-4cfc-912e-18e3b4c46ccd",
    "sender_id": 913877,
    "receiver_id": 965508,
    "company_id": null,
    "sender_company_department_id": null,
    "sender_department_name": null,
    "sender_company_site_id": null,
    "sender_site_name": null,
    "sender_grade_id": null,
    "sender_grade_name": null,
    "sender_company_designation_id": null,
    "sender_designation_name": null,
    "sender_company_business_unit_id": null,
    "sender_business_unit_name": null,
    "sender_cost_center_id": null,
    "sender_costcenter_name": null,
    "receiver_company_department_id": null,
    "receiver_department_name": null,
    "receiver_company_site_id": null,
    "receiver_site_name": null,
    "receiver_grade_id": null,
    "receiver_grade_name": null,
    "receiver_company_designation_id": null,
    "receiver_designation_name": null,
    "receiver_company_business_unit_id": null,
    "receiver_business_unit_name": null,
    "receiver_cost_center_id": null,
    "receiver_costcenter_name": null,
    "citation": "#Looknewemployee Nethra Nethra12 Congratulations !!!",
    "hashtags": null,
    "created_date": "2023-05-24 21:47:32",
    "status": "Published",
    "badge_id": 21713,
    "core_value": "LookNewEmployee",
    "sender_name": "Nethra",
    "sender_email": "[email protected]",
    "receiver_name": "Nethra12",
    "receiver_email": "[email protected]",
    "receiver_emp_id": "Demo1230",
    "sender_emp_id": "Demo1113",
    "image_url": "<https://imagestore-001.xoxoday.com/enterprise2/icons/ValueBadges/colored-Cordiality.png>",
    "group_id": "a7d7a413-6167-4891-bff2-74e288fcfb96-1602511408149"
    }
    ],
    "total": 1
    }
    }
    }

Global Error Handling

The OAuth API returns different error codes and messages depending on the nature of the error. The client can handle these errors to fail gracefully. These messages can also be used to provide guidance on expected actions from end users.

Here are some common error codes and messages that the OAuth API may return:

  • 400 Bad Request: Invalid request parameters.

    • award.InvalidEmailFormat

    • award.awardNotFound

  • 401 Unauthorised: Invalid or expired access token.

  • 403 Forbidden: The client does not have permission to access the requested resource.

  • 500 Internal Server Error: An error occurred on the server.


​

Did this answer your question?