How to use the myhrtoolkit API | myhrtoolkit HR software for SMEs

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"
            }
        ]
    }
}

Using the myhrtoolkit API - Technical Documentation

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

PHP cUrl example

PHP cUrl Example

Receiving a response

Call 0330 236 8399 for more information

Myhrtoolkit features

Information

Resources