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 set up 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 valid period.

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 you should securely save it for later use.

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

API Documentation

Swagger provides documentation for the API and describes the API and lists endpoints (the point of contact between an application and the API). You can find the ‘LeaveWizard Public API 1.0’ Swagger specification 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.

You can see 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, you can use other parameters such as ‘Status’ 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, you can now use API Management software such as Postman to test the API.

Authentication

Our API uses the Oauth2 authentication protocol, so 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 it 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 pop-up.

Test An API Call

Type in the request URL in the ‘Enter request URL’ field. You can make this from the base URL and the chosen endpoint. The base URL, as listed on Swagger, is:

https://api.leavewizard.com

and if you want to use the ‘Events’ endpoint to retrieve employee leave and absence events, then you 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. You can now enter the parameters for this endpoint ‘from’ and ‘to’. If you 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 Postman adds the parameters 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) you get the details, in this example, for the single sickness event for Janet Ayres on 27th January 2021.