_

Summary

• What is it
• How it works
  • Creating the API Token
  • Update it with Postman
  • Contest Logs

_

What is it

In Crewhu, you can update your contests based on an External Metric in an easy way by using an API.

Using an API Platform, such as Postman, you will be able to submit a request with the contest's results, in order to update your leaderboard in Crewhu.

-

How it works

Refer to the following steps to create the API token and update your contest.

-

Creating the API Token

• First, you have to enable the Contests Update via API in Crewhu. For that, go to Settings > Contests and enable the following option:

Note:
You are also able to choose which users will be notified in case of any update error, by selecting them on the Notify users drop-down field.

• Click on the Go to API Settings button (Settings > Integrations) to create the API Token;
• Click on +Add, type in a Description, and click on Confirm to create the Token. Simply click on Copy Token so you can copy the token to be used on your API tool;

-

Update the contest with Postman

For this example, we'll use Postman, which is an API Platform app where we can post the call to update the contest. Keep in mind that you can use any API tool you wish. 

In order to call the API, you will have to list the URL (our end-point), our Key, and its Value (Token) which are listed below.

In this case, using Postman, you'll have to create a POST type of call and fill in the following information:

URL: https://api.crewhu.com/api/v1/contest/metrics

Key: X_CREWHU_APITOKEN

Value: The token you've just created in Crewhu on the step above.

Note:
Refer to our Open API to know more.

Having set up the integration, now you'll have to send the results of your contest, in order to update the leaderboard. For this, you'll have to submit/post the call using a JSON format, with all the proper data, considering the following fields:

• MetricToken: The code of the External Metric used in your contest. Example:

• Timeframe:
  
  • DY: Daily
  • WK: Weekly
  • MO: Monthly
  • QT: Quarterly
  • YR: Yearly
• Identificator: The identification of the participant. This can be the users' Employee ID or their email addresses in Crewhu.
• Value: The sum of the users' results on the contest timeframe, as to be displayed on the leaderboard.

See the example below:

{
    "metricToken": "timemetric",
    "timeframe": "DY",
    "data": [
        { "identificator": "Bbardot", "value": 30 },
        { "identificator": "IBergman", "value": 79.99 },
        { "identificator": "ADelon", "value": 12 },
        { "identificator": "CGrant", "value": 50 },
        { "identificator": "MMastroianni", "value": 82 }
    ]
}

What it would look like on Postman:

After posting this API call, the contest will be updated with the results informed, meaning that it won't sum up with the existing results, but replace it with the last update.

Example of the contest leaderboard after this update used in our example:

-

Contests Logs

You are also able to keep track of the contests updates, to know if the calls are being processed properly. In order to verify that, simply go to Settings > Contests and click on View Updates Log, you'll be able to see the list of logs generated by the API Call of the contests. The successful updates are displayed in green, and contain the link to the contest as well: