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
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’
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 ‘
Then click ‘Get New Access Token’ to get the token and select ‘use token’ on the pop-up.
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 successful (status 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 response (status 200) will provide a list of event types, with details, for that company.
