The LeaveWizard API For Partners
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 a LeaveWizard partner or third-party can setup 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
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:
Beta: https://api-beta.leavewizard.com/swagger/ui/index
Production: https://api.leavewizard.com/swagger/ui/index
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 API
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 which 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 of the other endpoints are made available via the public API scopes, lw-public-api and lw-public-api-write. As a partner you will be given access to both the company-api and public-api scopes and you should specify all four scopes.
Request Header
As a partner you will be accessing the API on behalf of your organization and will therefore have control over all of 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 which includes the unique ID of the company.
Required Request Headers (Name : Value): companyUUID : <company_uuid>
Authorisation
When calling an API endpoint the access token must be sent as a bearer token using an HTTP Authorization header.
Testing The API
You can use API management software such as Postman to test the API. First we will generate an access token which can be used to register a new company and then we will use the ID of that company to get a list of it’s event types.
Generate A New Authorisation Token
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 Beta authentication server URL is https://beta-identity.leavewizard.com/connect/token
Client ID: Enter the Client ID you were given by our support team
Client Secret: Enter the Client Secret you were given by our support team
Scope: lw-public-api lw-public-api-write lw-company-api lw-company-api-write
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.
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. This is made 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 which 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 successful (200) response will provide the company ID “companyUUID” and administrator user ID “employeeUUID” 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 successful (200) response will provide a list of event types, with details, for that company.
