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}}×tamp={{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” will be UTC timestamp/EPOCH on the server side. Any request where the time difference is greater than 300 seconds will be rejected by our server.
For eg. |
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}}×tamp={{timestamp}}&hash={{hash}}&&landing_page=appreciationRefer 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}}×tamp={{timestamp}}&hash={{hash}}&&landing_page=homeRefer 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}}×tamp={{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
}
}
}
Approved: if the award is issued,
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.