All Collections
Using the Customer API Feature
Using the Customer API Feature

Getting started with all things API related

Updated over a week ago

On Workhub, the customer API feature can be found under the Account module. This feature is meant to allow you to view data from Workhub on any other softwares you might currently use. It allows you to use an API action to get worker data so it can be easily accessed without you having to log in to your Workhub account and view compliance from the Admin side. 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 side, click Account then select the API tab

You will see a popup with all our current API templates. These are created from our database. Currently, there are four templates available.

Once you've added the template, you will see it appear in the List.

On the API details page, you will see various settings. You can add a description or notes of your API call to reference in the future if necessary. You will also see that some fields have been populated like the Request Type and Request Template. These cannot be changed, although you can select your preferences for the Output Format (JSON & XML) and Parameters (WorkerIDNumber and FirstName&MiddleName&LastName).

As you make changes to the parameters, you will see that the Website Address will automatically update to reflect these changes. These parameters are what you will use in your program to access the data. These parameters must be set in order to use the API call.

You will also see the Client Key and Client Secret listed under the Authorization heading. This will be a different Authorization code for each API call which is created. You can use this code to determine who is using the API feature to gather data. You can create multiple requests with different Authorization codes, and this could be set up for different departments in your company like Sales, HR, etc. There is also a button here to Regenerate the Authorization code, if compromised.

If you are providing different API calls to different groups or individuals, you can make notes in the Request Description/Notes field to keep track of who has what set of Authorization credentials.

Now that we've covered the basics, we can use an app like Postman to test and access our API request.

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.

The same goes for WorkerIDNumber. That value needs to be replaced with the ID for the Worker as found in the URL when viewing a 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.

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 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.

Did this answer your question?