The LeaveWizard API

LeaveWizard provides a customer accessible public Application Programming Interface (API) to allow external applications to get information, such as a list of employee events (leave and absence requests), from LeaveWizard. This article explains how an administrator can setup and test the API.

From ‘Configuration’ on the main menu, select the ‘Company Settings’ sub menu from the drop down and then navigate down to the ‘API Access’ section on the page.

Registering An API Client

Initially the list of clients that are registered to use the API is unpopulated. So, you need to register a client and get an ID and Secret (password) from our server to use the API.

To do this, click the ‘Add client’ button on the page and a new page will then open where you can choose a name for the client and a time period for which the Secret is valid.

When you click Submit you will get a pop up displaying your Client ID and Secret which you will need to use the API. To the right of each is a ‘Copy’ button to allow you to copy each string to the clipboard. Although the Client ID is accessible on the LeaveWizard web app, the Client Secret is not and should be securely saved for later use.

Once you have successfully added a new client it is added to the list showing the name you chose and the client ID that was generated.

API Documentation

Documentation for the API is provided by Swagger and describes the API and lists endpoints (the point of contact between an application and the API). The ‘LeaveWizard Public API 1.0’ Swagger specifications can be found at:

https://api.leavewizard.com/swagger/ui/index

or you can click the ‘public API’ link in the ‘API Access’ section of the ‘Company Settings’ page where you registered your API client.

If you click on an individual listing, for example the ‘Events’ endpoint ‘GET /public/v1/events Retrieves employee leave and absence events’ it will open up to provide more detailed information with a list of parameters and responses.

It can be seen that the ‘Events’ endpoint requires the ‘from’ and ‘to’ parameters and these are both strings in ‘date-time’ format (for example ‘2021-04-13T14:18:43.042Z’). Optionally, other parameters such as ‘Status’ can also be used to get only certain leave or absence events such as those which are ‘Pending’.

Testing The API

With the API client registered and the Swagger documentation, we can now use API Management software such as Postman to test the API.

Authentication

Our API uses the OAuth2 authentication protocol which means that you need to get an access token from our server to allow you to communicate with the API. To do this go to the ‘Authorization’ tab on Postman and select ‘OAuth 2.0’ for ‘Type’

Then scroll down to the ‘Configure New Token’ section and set the ‘Grant Type’ to ‘Client Credentials’ and complete the other form fields as follows:

Token Name: Either choose a name for the token or leave blank for a generic name to be generated.

Access Token URL: Our authentication server URL is https://identity.leavewizard.com/connect/token

Client ID: Enter the Client ID you saved when you registered the client

Client Secret: Enter the Client Secret you saved when you registered the client

Scope: Use lw-public-api

Client Authentication: Select ‘Send as Basic Auth header ‘

Then click ‘Get New Access Token’ to get the token and select ‘use token’ on the popup.

Test An API Call

Type in the request URL in the ‘Enter request URL’ field. This is made from the base URL and the chosen endpoint. The base URL as listed on Swagger is:

https://api.leavewizard.com

and if we want to use the ‘Events’ endpoint to retrieve employee leave and absence events, then we use:

/public/v1/events

So, the complete URL for that endpoint is:

https://api.leavewizard.com/public/v1/events

Then go to the ‘Params’ tab on Postman. We can now enter the parameters for this endpoint ‘from’ and ‘to’. If we want to get events for January 2021 then

Key ‘from’

Value ‘2021-01-01T00:00:00.000Z’

Key ‘to’

Value ‘2021-01-31T00:00:00.000Z’

Notice that the parameters are added to the URL. Then click ‘Send’ to make the API call and see the result in the ‘Response’ section.

{
    "pageNumber": 1,
    "pageSize": 20,
    "itemsCount": 1,
    "items": [
        {
            "uuid": "1d5ffc4c-c1b8-4e05-9a53-f46c03e53206",
            "title": "Sickness",
            "creationDate": "2021-01-27T12:53:00Z",
            "startDate": "2021-01-27T00:00:00Z",
            "endDate": "2021-01-27T23:59:00Z",
            "duration": 1.00,
            "isInHours": false,
            "details": "",
            "status": "expired",
            "employee": {
                "uuid": "4c1f90f5-0272-478f-846b-b80e1be03018",
                "name": "Janet Ayres"
            },
            "eventType": {
                "uuid": "df12f8c4-7e79-42e8-aaef-014b1dd1a079",
                "name": "Sickness"
            },
            "workPattern": {
                "uuid": "e5f7a897-8f88-4150-b44f-a69c2bfc9cf6",
                "name": "7 days (5 work, 2 off)"
            },
            "coverEmployee": null
        }
    ]
}

If the call was successful (Status 200) we get the details for the single Sickness event for Janet Ayres on 27th January 2021.