Workhub offers a number of API calls that allow you to extract some basic data out of the software. These API calls can be utilized by numerous external programs, and once they're set up, you can skip the process of logging in to Workhub to review compliance numbers. You can use a third party app like Postman to access this data, or import into your own software.
Activating an API Call
To get started with setting up the API, the first thing you'll want to do is add an API call. From your Admin dash, click Account then select the API tab.
The page will start off blank. To activate an API call, you need to add the call. Click the Add Call button in the top right corner to select an API call to activate.
In the pop-up that appears, click the radio button for the call you want.
After selecting a call, click the Add button. The pop-up will close and you'll see a page of the details for your particular call.
The body of the page will include the fields that will be included in your API call. These fields will vary based on the call you've chosen. On the right side of the page you'll see the details in place for your call. They include:
Request type: this will always be GET
Workhub does not accept PUSH requests
Request Template: this is the Type of call
Request description/Notes: you can populate this field with any details that would be useful for someone accessing this page to make use of the various calls you have activated
notes can indicate which calls to use and when
notes can also indicate who the call is intended to be used by!
Output format: this is the format used to provide you the data you have requested
options include JSON or XML
Parameters: this is the criteria used by the call to identify what data you want to pull
the parameters will vary based on which call you activate
for calls based on Workers, the options will include:
WorkerIDNumber (this is the ID you assign a Worker in their Worker Profile)
Firstname&MiddleName&LastName (these are the names provided to a Worker in their profile)
Website Address: this is the URL needed to use your API call within your chosen program
Once you've made your desired changes to the details, click the Save button in the top right corner. After you do so, the Website Address and Authorization fields will populate with unique IDs for your particular call.
The Authorization box will populate with two portions: a Client Key and a Client Secret. These fields will allow secure use of your API call, so be sure to restrict their access to those who are trusted to run the call!
You'll see a Regenerate option beneath the Secret field. If your key or secret have been compromised, you can regenerate those two elements to re-secure access.
You can create multiple calls of the same type! The different keys and secrets are how your selected programs will be able to distinguish between calls if you choose to create multiple calls of the same type.
Once you have all your calls activated and details in place, you can try testing your calls using an external service. We provide a guide here for using Postman, an API platform, to test out your calls before putting them into use in other programs.
Using Postman to test your API call
Now that you have your call created, you may want to test it in Postman. When you are adding it into another system, it is a little tricky because each program looks different when trying to create the request.
The first step is to open your Postman app or browser window. You'll need to open a new workspace using HTTP. In your new request, you can enter the Website Address from your desired API call in the URL field:
When you are using any of the API calls available through Workhub, you will need to replace values found within the call to generate information digestible for a non-developer audience. For example, in the screenshot example above, the call was chosen to use the parameters "FirstName&MiddleName&LastName" for name information. In the Website Address generated for this API call, those fields appear as {{FirstName}}, {{MiddleName}}, and {{LastName}}. Those values, including the brackets, need to be replaced with the relevant data from the Workhub account in the call. So, for a Worker named Mo Finch, the call would end with FirstName=Mo&LastName=Finch.
If your desired Worker doesn't have a middle name, simple remove the Middle Name element of the Get call! You need to remove the entire string that includes "&MiddleName={{MiddleName}}".
The same goes for WorkerIDNumber. That value needs to be replaced with the ID for the Worker as found in their Worker profile in Workhub, as seen highlighted in this screenshot:
Once you've replaced the {{Name}} fields or the {{WorkerIDnumber}} with the necessary names or numbers, you'll see the FirstName and LastName or WorkerID values in the tables fill with what you've entered.
The next step is entering the Authorization credentials to allow your program to successfully pull information from Workhub. To do so, you'll need to add a Header to your request.
Click into your Headers tab. In the Key field, enter Authorization. In the Value field for that line, enter "amx ClientKey:ClientSecret" but replace the ClientKey and ClientSecret elements with the values listed in the Workhub fields.
While it seems like the likely place to enter them, the Authorization tab is not where you enter the Authorization ClientKey and ClientSecret values!
Once you've entered those values in their respective fields, you should be good to Send your Get request (or pull the information you're seeking from Workhub) by hitting Send next to the Get bar. If the call has been properly set up, that should populate the Body box at the bottom of the screen.
The results will look a little different depending on which output format you chose for your call.
For JSON, they should look something like this:
For XML, they should look something like this:
You can then download that response if you would like to use the response in another program, such as Power BI. To do so, click on the menu icon (three dots) in the top right corner of that box and choose Save Response to File. You can then give your file a name, and based on the output format you chose to call, you can pop a file extension on the end of your download (.json or .xml) to save your file as the correct type.
Need Help?
While it's not simple, setting up an API call can help make analysis of Workhub data much easier for you! It can be a tricky process, so if you run into any trouble or if you have any questions, you can always contact our Support Centre for assistance. You can click the orange question mark Help Chat button in the bottom left corner of your screen for chat support.
You can also email our Support Centre at [email protected].
Finally, if your account is on a paid plan, you can also call in for phone support. The number for our Support Centre is 1-888-668-6403.