Using the myhrtoolkit API

Introduction

This guide covers the new Application Programmers Interface (API) for the myhrtoolkit HR system. When combined with your in house or third party software, our API will allow you to automatically access and extract data from your myhrtoolkit account.
For those interested in building their own applications, integration through the myhrtoolkit API will add additional value, such as enabling bespoke reporting or integration with other business applications.

For a general introduction to APIs see here.

We are always interested in talking to customers considering using the API, so feel free to get in touch.
The aim of this document to enable developers to utilise the myhrtoolkit API for their own applications.
At present our API is read only and all requests other than authentication are GET.

Signing up to use the myhrtoolkit API

To be able to use the myhrtoolkit API, your organisation will need an Authentication key. Applying to receive one will require agreeing to terms and conditions which highlight that:

  • Your API credentials allow full controller-level access to any available API route. Any third party developing your application will have access to your data.
  • API access is available to you for internal use only. The API is intended for integration of myhrtoolkit and other applications it will not by used to replicate, rebrand or resell myhrtoolkit functionality without prior written agreement.
  • We reserve the right to rate limit requests if we believe your application is making too many requests.

 

Authenticating

We use the oAuth 2.0 standard for authentication. The first stage in any authentication cycle is to generate an access token for API use. This key is valid for 5 minutes.

POST https://api.myhrtoolkit.com/oauth/access_token

Required parameters:

grant_type This must be set to password.
client_id This is your client ID
client_secret This is your Authentication key
username This is the username of the controller you’re using for the API access
password This is the controller’s password

All parameters must be x-www-form-urlencoded.

 

PHP cUrl example

$curl = curl_init();
curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api.myhrtoolkit.com/oauth/access_token",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "grant_type=password&client_id=YOUR_CLIENT_ID
         &client_secret=YOUR_CLIENT_SECRET&username=YOUR_CONTROLLER_USERNAME
         &password=YOUR_CONTROLLER_PASSWORD", 
    CURLOPT_HTTPHEADER => array( "cache-control: no-cache", "content-type: application/x-www-form-urlencoded" ), )); 

$response = curl_exec($curl);

On a successful request, the response will be in the following JSON format.

{
    "access_token": "RNShyENb3HCrPds3rAS2OJibe76ISfqM2qi729rr",
    "token_type": "Bearer",
    "expires_in": 3600
}

If a failed request is made, the response will be as follows:

{
    "error": "invalid_client",
    "error_description": "Client authentication failed."
}

The error and error_description values will reflect the reason for the failure, such as invalid client_id or client_secret in the above example, or unsupported_grant_type.
The API user has access to all client data. In effect, they access your information as a controller.

 

Making a request

With a valid access token, requests to the API can now be made.
Each request must include the supplied access token within the Authorization header.
Requests made without or an invalid authorization token will receive as response with a 400 status code similar to:

{
    "error": "invalid_request",
    "error_description": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the \"access token\" parameter."
}

Additional parameters may be sent in the URL query string. These are described in the relevant sections below.

PHP cUrl Example

$curl = curl_init();
    curl_setopt_array($curl, array(
    CURLOPT_URL => "https://api.myhrtoolkit.com/public/users/1",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => array(
    "authorization: Bearer 7H4FVwZ1w3qDuqUbjINA3MeO9DHKcldWnzbu72Fz"
    ),
));

$response = curl_exec($curl);

Receiving a response

All responses are in JSON format with a root object labelled “data” and a status code of 200.
An example response for a request to GET /public/users/123

{
    "data": {
        "id": 123,
        "created": "2006-01-19 16:23:16",
        "contact_id": "225",
        "department": "Sales",
        "location": "New York",
        "firstname": "Peter",
        "surname": "Green",
        "gender": "Male",
        "email": "[email protected]",
        "telephone": "+441142563435",
        "links": [
            {
                "rel": "self",
                "uri": "/public/users/123"
            }
        ]
    }
}

Date and Time formats

All dates and times are in ISO format of YYYY-MM-DD HH:MM:SS

Pagination

By default, all responses are paginated and return 50 records at a time.
Details of the current pagination is given in the meta attribute of the response as shown in the example below.

"meta": {
    "pagination": {
        "total": 135,
        "count": 50,
        "per_page": 50,
        "current_page": 1,
        "total_pages": 3,
        "links": {
            "next": "https://api.myhrtoolkit.com/public/departments/123/users/?page=2"
        }
    }
}

The URL required to continue to the next page is given in the links:next attribute.

API Endpoints

 

Users

 

GET /public/users Returns a list of all users for your organisation.
GET /public/users/{id} Return summary information for the selected user.
GET /public/users/{id}/holidays Returns a list of all holidays for the selected user within the current calendar year.

Allowed parameters:
year=YYYY
The year for which you wish to display holidays.

GET /public/users/{id}/holidaydashboard Returns a summary of the selected user’s holiday information for the current holiday year.

 

Holidays

 

GET /public/holidays Returns a list of holidays for your organisation.

Allowed parameters:
year=YYYY
The year for which you wish to display holidays.

GET /public/holidays/{id} Returns summary details for the requested holiday id.

 

Locations

 

GET /public/locations Returns a list of locations for your organisation.
GET /public/locations/{id} Returns summary details for the requested location.
GET /public/locations/{id}/users Returns a list of users in the requested location.
GET /public/locations/{id}/holidays Returns a list of holidays for users in the requested location.

 

Departments

 

GET /public/departments Returns a list of departments for your organisation.
GET /public/departments/{id} Returns summary details for the requested department.
GET /public/departments/{id}/users Returns a list of users in the requested department.
GET /public/departments/{id}/holidays Returns a list of holidays for users in the requested department.

 

Salaries

 

GET /public/salaries Returns a list of salary information for all users in your organisation.
GET /public/salaries/user/{id} Returns salary information for the requested user.
GET /public/departments/{id}/salaries Returns a list of current salary information for all users of the requested department.