🖥️Empuls Software Development Kit

Integration Guide for Intranet Sites

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

2. Appreciate (Webview & API)

3. Send Gifts (API)

4. Redeem Reward Points

5. Home Page

6. Reports

   1. Fetch Awards Issued API

   2. Fetch Core Values API

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:[e-mail]
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: [e-mail]' \\
-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

Appreciate Webview on MS Teams App

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: [e-mail]' \\
  -H 'Content-Type: application/json' \\
  -d '{
     "award_id": "xxxxxxxxxxxxxxxxxx",
     "recipients": ["[e-mail]","[e-mail]"],
     "budget_id": "xxxxxxxx",
     "citation_message": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
     "points": 10,
     "group_id": "xxxxxxxxxxxxxxxxxxxxxx"
  }'

• Header

  Header Key	Value	Comments
  authorization	Bearer Token	Token obtained from Authorisation
  as_user	URL encoded email id of the user who is performing the action	String. Required.
  content-type	application/json

• Payload

  JSON Key	Value	Comments
  award_id	Id of the award created on the Empuls platform.	String. Required. Only Spot/Instant awards can be given. Approval-based awards are not supported.
  recipients	An array of email ids of the recipients	String Array. At least one recipient email id is required.
  citation_message	Message to be added as part of the appreciation	String. Required. Upto 1000 characters supported.
  budget_id	The budget id of budget from where the points have to be used for giving this award (https://www.hippovideo.io/video/play/B3YvXjLag3MTPIoEPolTFYxgNL_NvfziL6Jx2gNJlU8?hvlk=er6kZlbeLQEZ&org_tok=9fInNo4SxfS7he-wYFN20g&hvre=false&_=1685002649514 to learn how to get the budget id of a budget)	Unsigned Integer. Optional. If not provided, the system will automatically choose the relevant budget based on the award_id and the sender.
  points	Points to be given to the recipients. If more than one recipient is provided, then based on the award configuration, it will either be split or given equally.	Unsigned Integer. Optional. If not provided, will be taken as default/minimum points for the award.
  group_id	The id of the group where the appreciation message should be posted.	String. Optional. If not provided, the default (homepage) group would be chosen for posting.

• Response

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

  JSON Key	Value	Comments
  success	0 or 1	Unsigned Integer. 1 indicates success, and 0 for failure.
  status	200, 201, or Global Error codes	Unsigned Integer. 200, 201 indicates success, and others for failure. Refer global error handling section below for other error codes.
  message	Human readable description regarding the API response	String.
  appreciation_id	Unique id for the resource created	String. Optional. blank in case of error.
  error_code	null or one of the unique error identifier	String

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.

Send Gifts Experience (For Integrations)

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: [e-mail]' \\
  -H 'Content-Type: application/json' \\
  -d '{
     "gift_id": "xxxxxxxxxxxxxxxxxx",
     "recipients": ["[e-mail]","[e-mail]"]
  }'

• Header

  Header Key	Value	Comments
  authorization	Bearer Token	Token obtained from Authorisation
  as_user	URL encoded email id of the user who is performing the action	String. Required.
  content-type	application/JSON

• Payload

  JSON Key	Value	Comments
  gift_id	This is the id of the event from which you intend to send the gift. https://www.hippovideo.io/video/play/gCHkzloq8EeAMIo5xfUXTVrDDFI8hN17-BWWySJTtFk?hvlk=ybGPvMqwZk6M&org_tok=9fInNo4SxfS7he-wYFN20g&hvre=false&_=1685003035520 to learn how to get the gift id of an event.	String. Required.
  recipients	An array of email ids of the recipients. The email id should have an enabled user account on Empuls.	String Array. Required. At least one recipient email id is a must.

• Response

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

  JSON Key	Value	Comments
  success	0 or 1	Unsigned Integer. 1 indicates success, and 0 for failure.
  status	200, 201, and Global Error codes defined below	Unsigned Integer. 200, 201 indicates success, and others for failure. Refer global error handling section below for other error codes.
  message	Human readable description regarding the API response	String.
  gift_transaction_id	Unique id for the resource created	String. Optional. Blank in case of error.
  error_code	null or one of the unique error identifier	String. Blank in case of the successful transaction.

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

Web view of Empuls Store

• 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=redemption

  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

Home Page Web view

• 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: [e-mail]' \\
  -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

  Header Key	Value	Comments
  authorization	Bearer Token	Token obtained from Authorisation
  content-type	application/JSON

• Payload

  JSON Key	Value	Comments
  limit	Indicates the maximum number of records you intend to fetch.	String.
  start_date	Starting date of the date range you intend to get the appreciations.	Required.
  end_date	Ending date of the date range you intend to get the appreciations.	Required.
  timezone	UTC offset to indicate the timezone for consideration of date.	Required. Incase the date requested is for India region, send +5:30, For US EST timezone send -5:00 and so on
  sorting	Ordering of the messages between the timezone	Only fdc:desc & fdc:asc are accepted.

• 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": "[e-mail]",
                  "employee_id": "Demo901"
                }
              ]
            },
            "nominee_details": {
              "success": 1,
              "data": [
                {
                  "employee_first_name": "Chirag DEMO",
                  "employee_middle_name": "",
                  "employee_last_name": "12",
                  "employee_email": "[e-mail]",
                  "employee_id": "Demo903"
                }
              ]
            },
            "approver_details": {
              "success": 1,
              "data": [
                {
                  "employee_first_name": "CHIRAG1",
                  "employee_middle_name": "",
                  "employee_last_name": "SHARMA",
                  "employee_email": "[e-mail]",
                  "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
      }
    }
  }

  JSON Key	Value	Comments
  success	0 or 1	Unsigned Integer. 1 indicates success, and 0 for failure.
  status	200, 201, and Global Error codes defined below	Unsigned Integer. 200, 201 indicates success, and others for failure. Refer global error handling section below for other error codes.
  approval_status	Status of the award.	Possible values include

  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: [e-mail]' \\
  -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

  Header Key	Value	Comments
  authorization	Bearer Token	Token obtained from Authorisation
  content-type	application/JSON

• Payload

  JSON Key	Value	Comments
  limit	Indicates the maximum number of records you intend to fetch.	String.
  start_date	Starting date of the date range you intend to get the appreciations.	Required.
  end_date	Ending date of the date range you intend to get the appreciations.	Required.
  timezone	UTC offset to indicate the timezone for consideration of date.	Required. In case the date requested is for the India region, send +5:30, For the US EST timezone send -5:00, and so on
  sorting	Ordering of the messages between the timezone	Only fdc:desc & fdc:asc are accepted.

• 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": "[e-mail]",
            "receiver_name": "Nethra12",
            "receiver_email": "[e-mail]",
            "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
      }
    }
  }

  JSON Key	Value	Comments
  success	0 or 1	Unsigned Integer. 1 indicates success, and 0 for failure.
  status	200, 201, and Global Error codes defined below	Unsigned Integer. 200, 201 indicates success, and others for failure. Refer global error handling section below for other error codes.
  status	Status of the award.	Possible values include

  1. Published: if the recognition is published on an Empuls group

  2. Deleted: If the published recognition message was deleted | | group_id | Id of the Empuls group where the message is published | String. | | citation | Recognition message shared by the sender | | | 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. |

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.