< All Topics
Print

The LeaveWizard API For Partners

This article is specific to the LeaveWizard API for partners, which provides additional capabilities for them. If you are not a partner, please refer to The LeaveWizard API article.

The customer accessible public Application Programming Interface (API) allows external applications to get information, such as a list of employee events (leave and absence requests) from LeaveWizard. This article explains how a LeaveWizard partner or third-party can set up and test the API.

Registering A Partner API Client

In order to access the LeaveWizard API as a partner or third-party, you will need to request a client ID and Secret (password) from our support team. This is because the LeaveWizard API uses client credentials and OAuth2 authentication, and you will need these to gain access. You should receive two sets of credentials, one for Beta and one for production system access.

API Documentation

We provide Swagger documentation for the API which 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 specifications at:

Beta: https://api-beta.leavewizard.com/swagger/ui/index

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

A screenshot showing the Swagger 'LeaveWizard Public API 1.0' page for Beta, listing the endpoints available.

If you click on an individual listing, it will open up to provide more detailed information with a list of parameters and responses.

Using The LeaveWizard API For Partners

In order to use/consume the API, you will first need to get an access token using the credentials provided. To get an access token using API Management software such as Postman, you will need to use the following.

Grant Type: Client Credentials

Access Token URL: https://beta-identity.leavewizard.com/connect/token

Client ID: <Your-Client-Id>

Client Secret: <Your-Client-Secret>

Scope: lw-public-api lw-public-api-write lw-company-api lw-company-api-write

Scopes

Scopes are used to restrict which endpoints are available to specific API clients. As a partner, you will have access to the ‘Companies’ endpoint as shown in the swagger list. This will enable you to perform Create, Retrieve, Update and Delete (CRUD) actions for companies. The scopes required for this are lw-company-api and lw-company-api-write. All the other endpoints are available via the public API scopes, lw-public-api and lw-public-api-write. As a partner, you have access to both the company-api and public-api scopes and you should specify all four scopes.

Request Header

As a partner, you will access the API on behalf of your organization and will therefore have control over all the company accounts that you create via the API.

In order to determine which company you would like to access the API on behalf of, it is necessary to provide a request header. This includes the unique ID of the company.

Required Request Headers (Name : Value): companyUUID : <company_uuid>

Authorisation

When calling an API endpoint, you must send the access token as a bearer token using an HTTP Authorization header.

Testing The LeaveWizard API For Partners

You can use API management software such as Postman to test the API. First, we will generate an access token to register a new company and then we will use the ID of that company to get a list of its event types.

Generate A New Authorisation Token

Our API uses the OAuth2 authentication protocol, which means 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’

A screenshot showing the authorization tab on Postman and OAuth 2.0 selected as the type.

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

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

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

Client ID: Enter the Client ID our support team gave you

Client Secret: Enter the Client Secret our support team gave you

Scope: lw-public-api lw-public-api-write lw-company-api lw-company-api-write

Client Authentication: Select ‘Send as Basic Auth header ‘

A screenshot showing the the configure new token section of the authorisation tab with the grant type set to client credentials.

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

A screenshot showing the new access token.

Registering A New Company

To create a new company, you need to use the POST companies endpoint. Type in the request URL in the ‘Enter request URL’ field. You can make from the base URL and the chosen endpoint. The base URL for Beta as listed on Swagger is:

https://api-beta.leavewizard.com

and the POST ‘Companies’ endpoint is:

/public/v1/companies

So, the complete URL is:

https://api-beta.leavewizard.com/public/v1/companies

This endpoint requires parameters to be specified in the body. These provide the required company and administrator user information. Select the ‘Body’ tab and use JSON raw format, as shown in the example, to enter these required values:

{

“firstName”: “Paul”,

  “lastName”: “Test”,

  “companyName”: “PaulTest”,

  “email”: “[email protected]”,

  “password”: “1234567”,

  “acceptTerms”: true

}

A screenshot showing the body tab with data in JSON raw format for a POST companies endpoint.

A successful (status 200) response will provide the company ID “companyUUID” and administrator user ID “employeeUUID” values.

A screenshot showing the Postman responce area with a successful result returning the company ID and administrator user ID values.

Using The Company ID In A Header

The following example shows how to use the Company ID you received when you registered the company in a request header to get a list of the company event types using the GET event_types endpoint.

URL: https://api-beta.leavewizard.com/public/v1/event_types

In the ‘Authorization’ tab, select the same token and then select the ‘Headers’ tab and add the companyUUID that was returned when you created the company. Please note that you should use the key name ‘companyId’ rather than ‘companyUUID’.

A screenshot showing the company ID added to the request header to get a list of the company event types using the GET event_types endpoint.

A successful response (status 200) will provide a list of event types, with details, for that company.

A screenshot showing the Postman responce area with a successful result returning a list of event types, with details, for that company.

Table of Contents