--- title: How to use the myhrtoolkit API | myhrtoolkit HR software for SMEs description: This guide covers how to use the Application Programmers Interface (API) for myhrtoolkit. Our API allows you to access and extract data from your account. --- ** Call us ** Menu ** [0345 225 0414](tel:03452250414) - [Customer Support **](https://www.myhrtoolkit.com/support) - [Login **](https://app.myhrtoolkit.com/user_portal/) [![myhrtoolkit-agilio-logo-colour-800px](https://www.myhrtoolkit.com/hs-fs/hubfs/Logos%20and%20Brand/myhrtoolkit-agilio-logo-colour-800px.png?width=800&height=82&name=myhrtoolkit-agilio-logo-colour-800px.png "myhrtoolkit-agilio-logo-colour-800px")](http://myhrtoolkit.com) [![myhrtoolkit-agilio-logo-white](https://www.myhrtoolkit.com/hs-fs/hubfs/Logos%20and%20Brand/myhrtoolkit-agilio-logo-white.png?width=1000&height=103&name=myhrtoolkit-agilio-logo-white.png "myhrtoolkit-agilio-logo-white")](http://myhrtoolkit.com) # 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](https://www.codenewbie.org/blogs/an-intro-to-apis). 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](https://www.myhrtoolkit.com/support/myhrtoolkit-api). ** 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" } ] } } ``` This is a search field with an auto-suggest feature attached. - There are no suggestions because the search field is empty. - User Guides - Configuration - First Time Setup - [Overview](https://www.myhrtoolkit.com/support_categories/overview/) - [Login/passwords](https://www.myhrtoolkit.com/support_categories/login-passwords/) - [Multi-factor Authentication](https://www.myhrtoolkit.com/support_categories/multi-factor-authentication-guides) - [Holidays](https://www.myhrtoolkit.com/support_categories/holidays/) - [Absence](https://www.myhrtoolkit.com/support_categories/absence/) - [Communications](https://www.myhrtoolkit.com/support_categories/communications/) - [Document library](https://www.myhrtoolkit.com/support_categories/document-library/) - [Performance Management](https://www.myhrtoolkit.com/support_categories/performance-management) - [Starters and leavers](https://www.myhrtoolkit.com/support_categories/starters-and-leavers/) - [Training](https://www.myhrtoolkit.com/support_categories/training/) - [Pay and Benefits](https://www.myhrtoolkit.com/support_categories/pay-benefits) - [Reports](https://www.myhrtoolkit.com/support_categories/reports/) - [Tasks](https://www.myhrtoolkit.com/support_categories/tasks/) - [Variable hours](https://www.myhrtoolkit.com/support_categories/variable-hours/) - [Mobile app](https://www.myhrtoolkit.com/support_categories/mobile-app/) - [Complete guides](https://www.myhrtoolkit.com/support_categories/complete-guides/) - [Support policies](https://www.myhrtoolkit.com/support-policies-guides-myhrtoolkit) - [Rights/permissions](https://www.myhrtoolkit.com/support_categories/rights-permissions/) - [Holidays configuration](https://www.myhrtoolkit.com/support_categories/holidays-configuration/) - [Absence configuration](https://www.myhrtoolkit.com/support_categories/absence-configuration/) - [Hours](https://www.myhrtoolkit.com/support_categories/hours/) - [People management](https://www.myhrtoolkit.com/support_categories/people-management/) - [Health and safety](https://www.myhrtoolkit.com/support_categories/health-safety/) - [Performance Management](https://www.myhrtoolkit.com/support_categories/performance-management-config) - [Configuration](https://www.myhrtoolkit.com/support_categories/configuration-configuration/) - [Bulk data](https://www.myhrtoolkit.com/support_categories/bulk-data/) - [Omnibox](https://www.myhrtoolkit.com/support_categories/omnibox/) - [Import/export](https://www.myhrtoolkit.com/support_categories/import-export/) - [Troubleshooting](https://www.myhrtoolkit.com/support_categories/troubleshooting/) - [API](https://www.myhrtoolkit.com/support_categories/api/) - [User manuals](https://www.myhrtoolkit.com/support_categories/user-manuals/) - [Partner guides](https://www.myhrtoolkit.com/support_categories/partners-guides/) - [Step-by-step guide](https://www.myhrtoolkit.com/support/initial-setup-guide/) - [Additional guides](https://www.myhrtoolkit.com/support_categories/additional-guides/) ## Call 0330 236 8399 for more information [![Start Free Trial](https://no-cache.hubspot.com/cta/default/5034683/32edf79f-df3d-4f77-b258-8520c8086894.png)](https://cta-redirect.hubspot.com/cta/redirect/5034683/32edf79f-df3d-4f77-b258-8520c8086894) #### Myhrtoolkit features #### Information #### Resources t: 0330 236 8399 e: [enquiries@myhrtoolkit.com](mailto:enquiries@myhrtoolkit.com) [**](https://www.facebook.com/myhrtoolkit) [**](https://twitter.com/myhrtoolkit) [**](https://www.linkedin.com/company/myhrtoolkit-limited) © 2021 myhrtoolkit Limited, HR software on demand. All rights reserved. Various trademarks held by respective owners. Unit 18 Jessops Riverside, 800 Brightside Lane, Sheffield S9 2RX Remove cookies    ** Top ```json // Business name, address, opening hours, logo social profiles { "@context" : "http://schema.org", "@type": "LocalBusiness", "@id": "/support/how-to-guides/using-myhrtoolkit-api/", "name" : "Myhrtoolkit Ltd", "logo" : "https://www.myhrtoolkit.com/hubfs/Logos%20and%20Brand/favicon-teal.svg", "image" : "https://www.myhrtoolkit.com/hubfs/Logos%20and%20Brand/favicon-teal.svg", "url": "https://www.myhrtoolkit.com/", "address": { "@type": "PostalAddress", "streetAddress": "Unit 18 Jessops Riverside", "addressLocality": "Sheffield", "addressRegion": "South Yorkshire", "postalCode": " S9 2RX" }, "telephone": "0345 225 0414", "openingHours": [ "Mo-Fr 09:00-17:30" ], "email" :"sales@myhrtoolkit.com", "sameAs" : [ "https://twitter.com/myhrtoolkit", "https://www.linkedin.com/company/myhrtoolkit-limited", "https://plus.google.com/+myhrtoolkit" ], "description": "HR Software for SMEs" } } ``` ```json // Colloquial site name - for mobile SERPs { "@context" : "http://schema.org", "@type" : "WebSite", "name" : "myhrtoolkit", "url" : "https://www.myhrtoolkit.com/" } ```