Links
🖥

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

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",
    "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.
P.S: Unlike Awards, Gifts do not generate any feed messages on townhall or any groups.
  • 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
  • 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
  • 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
    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": "[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
    }
    }
    }
    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. 1.
      Approved: if the award is issued,
    2. 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
    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": "[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
    }
    }
    }
    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. 1.
      Published: if the recognition is published on an Empuls group
    2. 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.