Using the myhrtoolkit API - Technical Documentation

This guide covers the 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 CodeNewbie's Intro to APIs.

We are in the process of adding additional end points and write functionality. Rather than a single 'big bang' approach, it is being developed in parallel with our refactoring of each functional area. As such it will be rolled out progressively with end points being made available module by module. An authentication module is in the pipeline.
 
Although we are not necessarily in a position to accelerate the roll out, we are nonetheless interested in what our customers are seeking to do with the API.

The aim of this document to enable developers to utilise the myhrtoolkit API for their own applications. All requests other than authentication are GET.

For details of how to sign up to gain access to use the myhrtoolkit API, and how to create and store authentication keys, see this introductory document.

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 client_credentials
client_id This is the key ID as given in Config > API Access > Keys
client_secret This is key secret as shown in Config > API Access > Keys > View details

 

 

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=client_credentials&client_id=YOUR_KEY_ID
&client_secret=YOUR_KEY_SECRET", CURLOPT_HTTPHEADER => array( "cache-control: no-cache" ), )); $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": "me@work.com",
        "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.
API Endpoints: 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.
API Endpoints: 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.
API Endpoints: 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.
API Endpoints: 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.
API Endpoints: Benefits
GET /public/benefits Returns a list of active benefits for the organisation.
GET /public/benefits/{id} Returns details of a single benefit.
GET /public/benefits/{id}/user Returns a list of active users who are currently assigned to a single benefit.
GET /public/users/{id}/benefits Returns a list of benefits for the specified user.

We return the following information for each benefit:

 {
    "data": {
        "id": 123,
        "contact_id": 456,
        "title": "Company Lottery",
        "notes": "Text notes go here",
        "date_created": "2017-03-16",
        "created_by_user_id": 1234,
        "links": [
            {
                "rel": "self",
                "uri": "/public/benefits/123"
            }
        ]
    }
}
  • There are no suggestions because the search field is empty.