Home Features Tour Pricing
Blog Support Contact us
Call us today on +44 (0)1227 812932 Get your FREE Trial

WhosOff API

Welcome to the WhosOff API, which you can use to integrate into your other applications and work flows.

This outlines the Remote API provided WhosOff®. Primarily this API has been developed for integration with account holders’ internal systems.


Overview: Fair Usage and Authorisation API Access


Authenticate Company Message Department Free Restricted Leave Leave Type Lookup Map User Tag Overtime Overtime Type Reporting Sandbox System Message Tag User User Allowance User Note User Restriction Whosoff Work

API Access

The API requires authorisation and is not available with trial accounts.

To access the API you will need an API token, which a Super User will be able to manage through "Company settings" on your account.

Each user with access to the API will be able to access all calls available within the API. Please bear this in mind when you distribute access credentials.

Fair usage

Use of this API and associated data is at your own risk and responsibility, please be aware that we do not implement any of the data rules applied by the online system eg ‘cross dept viewing’ and other leave associated restrictions. If required, you will need to implement this in your own application.

Response types
Code Status Description
200 OK Request accepted and data returned via JSON
400 Bad Request Request rejected return error message via JSON
404 Page not found Endpoint not valid

For more information on responses, check out our complete list of response codes.

Sample

The following samples show a typical response from the WhosOff API.

Typical response object { "Data":[ "Record_ID":"9387447" ], "Errors": [ { "Code": "004a", "Message":"No allowances set" }, { "Code": "00422", "Message":"User limit reached" } ] }


Authorisation & security

In order to request access to your data, authentication needs to be successfully completed to obtain a bearer token. This can be done in two ways; by supplying user credentials (username and password) or through a valid access token. Alongside the credentials or access token, an IP address, a number once (nOnce), a secret, and a unique App Id must also be supplied. See API Authenticate Object for more information on the request and response objects.


Create an access token
Step 1: Obtain app credentials

In this section, we create an access token.

For example, our app credentials might be app_id = "MN500Q8lk5jp0rEm" secret = "QtOSeNmh3DY6AuMO" (client secret)

Step 2: Generate a random nonce value

This can be any random string but should be unique every time.

Example, random nonce nonce="2029-03-14T13:24:10.832Z"

Step 3: Calculate the secret

The secret is calculated according to the following structure:

Example, calculate using Secure Hash Algorithm // secret = SHA512(nonce + secret) secret = SHA512(2029-03-14T13:24:10.832ZQtOSeNmh3DY6AuMO"

Step 4a: Authenticate with credentials

Valid username and password of a user within your account.

Authenticate with credentials curl --location --request GET '{root}/authenticate/with-credentials' \ --header 'Content-Type: application/json' \ --data '{ "username": "{username}", "password": "{password}", "ip_address": "{ip_address}", "nonce": "{nonce}", "secret": "{secret}", "app_id": "{app_id}" }'

Step 4b:Authenticate with access token

Obtained from a successful credential authentication. This should be used to refresh an expired token.

Authenticate with access token curl --location --request GET '{root}/authenticate/with-access-token' \ --header 'Content-Type: application/json' \ --data '{ "access_token": "{access_token}", "ip_address": "{ip_address}", "nonce": "{nonce}", "secret": "{secret}", "app_id": "{app_id}" }'

IP address

IP address needs to be supplied to check if the request has permission from that location. Multiple IP address ranges can be added by the super user within WhosOff.

nOnce (number once) - generated by developer on each new authentication request

nOnce is a randomly generated, unique, 32 character string which is used in conjunction with the client secret to create a unique single use SHA512 hash.
Note: this could be the current DateTime to millisecnds '2029-03-14T13:24:10.832Z' and/or a Guid - so long as it is never reused.

Secret

The secret is a unique single use string which is created using the nOnce + supplied client secret (obtained in company settings) then hashed using the SHA512 algorithm.

App Id - obtained in company settings

The App Id is supplied to identify your unique API application. This is used in the initial request for an access token and in all proceeding calls in the call header.




Bearer token

Once authentication has been successful, an access token will be returned. This should now be used as in the example below along side your app-id and the content type 'application/json'.

Example call to get user by id curl --location --request GET '{root}/user/get-by-id/{user_id}' \ --header 'Authorization: Bearer {access_token}' --header 'app-id: {app-id}' --header 'Content-Type: application/json' \ --data '{}'

Testing your connector

It is strongly recommended that all testing uses the sandbox root while you build your custom integration - this can be found in company settings. To test your first authentication, you may wish to use Postman to ensure the connection is working. Please also be aware that any writing, editing and deletion of your live data is permanent and directly impacts your own data. Any changes to your data are your responsibility, so please ensure you have tested extensively in sandbox before pointing to the live root.

Unauthorised calls

Any unauthorised called will get a standard 400 response explaining why the authorisation failed. Below is an example of an invalid token. This could require reauthentication with credentials or a renewal of an expired token.

Example 400 response for Invalid Token { "Data":[], "Errors": [ { "Code": "TOK004", "Message":"Invalid Token" } ] }

Response object

Compressed Gzip responses

When responses are given from the API, the content encoding of the response will need to be checked. If the value matches Gzip the response stream will need to be decompressed before it is deserialized.

If the response does not contain Gzip in the "content-encoding" parameter, the response can be deserialized directly into your object.

For more information regarding Gzip, we would recommend heading over to StackOverflow and follow guides on decompressing Gzip


HTTP status codes

The HTTP status codes and their meaning are as follows:

Status code Message Description
200 OK A successful API call/action has been received.
400 Bad request The API request has an error in it.
401 Not Authenticated Can’t authenticate with those credentials. Check credentials and get a new access token if error persists.
403 Forbidden Permission not granted to execute API call/action.
500 Internal Server Error Something unexpected happened, contact WhosOff support.
502 Bad Gateway Unable to communicate with API server, contact WhosOff support.
504 Timeout Unable to complete call/action within permitted time, contact WhosOff support

Sample responses

The following samples show typical responses you may see.

Typical 200 response { "Data": [ { "Name": "Holiday / Vacation" }, { "Name": "Out of Office" } ], "Errors":[] }

Typical 400 response { "Data":[], "Errors": [ { "Code": "004a", "Message":"Date range can only be for a maximum of 365 days" } ] }


INSTANTLY REDUCE TIME SPENT ON LEAVE MANAGEMENT

Get your long FREE trial today!

No obligation and no payment setup required.
Sign up today and get until Thursday, 25th April 2024 to try the full service, for Free!
 

Start Your Free Trial