HRider
| HRider API
Español | English

Introduction

The HRider API offers you various RESTful Web Services, with which you can:
  • Create and modify Companies.
  • Create and modify Administrators.
  • Assign to an administrator permissions to manage one or more companies.
  • Create and modify Departments and Job Positions.
  • Create and modify Employees.
  • Assign supervisor and clients relationships to an employee.
  • Obtain company's Appraisals
  • Obtain and resend Invitations to take part in an appraisal.
  • Get the global reports for an appraisal.
  • Get the personal reports for an employee in an appraisal.
The API is designed following the HATEOS (Hypermedia as the Engine of Application State) principle, allowing a simple and consistent way to use and discover the API by following the links that each resource provides. See in the Java section what it would be like to use the API from a programming language and the simplicity and elegance of the client code that this principle provides.
The following UML diagram shows the main conceptual resources the API works with and how they relate to each other:
Premium Account. A PREMIUM account can create as many Companies and Administrators as they want. Each Administrator can have permission to access several Companies.

Department / Position. The organization of a Company has a tree structure where the nodes are Departments and the tree's leaves are Job Positions. A Department can have one or none parent department, and a Position will always belong to a single Department.

Employee. Company's employees can have 3 different types of relationships with other employees: supervisor, client y colleague. An employee can have one or none assigned supervisor, and none or several clients. The "colleague" relationship is implicitly established by the relationship that an employee maintains with the rest of the employees in the same position.

Appraisal / Report / FeedbackReport. Each one of the appraisals created in HRider can generate different depending on their type. Furthermore, regarding feedback appraisals, an evaluated person could also have their own personal report (FeedbackReport).

Invitation. Employees who participate in an appraisal receive an invitation to participate in it as evaluators. The invitation is sent by email and gives access to complete the surveys assigned to the evaluator.

Get an API Key

To get started, get an API Key that will be included in the header of each API call that will authenticate us to perform different operations. To do it, the owner of the PREMIUM account logs in HRider and from My Account accesses to the Connections > API Keys menu and clicks to Create New:
It is possible to create as many API Keys as wanted and assign different permissions to each one. From the edit API Key screen it specifies which companies have access to the API Key, and from Permissions it specifies whether access will be read/write or read-only for each of the resources:
To add security, from allowed IPs, a list of IPs (separated by commas) can be designated for which only access will be allowed. Any other call from an IP not included in the list, will be rejected.

Autentification

The API Key obtained must be included in the header "authorization" in each of the calls made. For example, given the API key oC0aGOzvwLSHJaDQ5kJv2bavrtmjkkYRAnb8BVoN if we want to get the API root recources, the Curl call could be:

curl -i -X GET 'https://dev.hrider.net/api/v1' \
-H 'authorization: bearer oC0aGOzvwLSHJaDQ5kJv2bavrtmjkkYRAnb8BVoN'
                    

Concepts

› Format

All the Web Services return a JSON object expressed in HAL Language. It is made of 3 parts:
  • Object own attributes
  • An attribute _links containing links to other resources to which the object is related
  • An attribute _embedded with a summary of each of the objects with which it is related.

Example of any Employee object's JSON:

    {
        "_embedded":{
                "company":{
                    "id":8113,
                    "name":"ACME SOLUTIONS"
                },
                "position":{
                    "id":8348,
                    "code":"W.DESIGNER",
                    "name":"WEB DESIGNER"
                },
                "supervisor":{
                    "id":9121,
                    "code":"EMP001", 
                    "email":"emp001@acme.com", 
                    "firstName":"ROGER", 
                    "lastName":"OLIVER", 
                    "photo":"12345"
                },
                "clients":[]},
        "_links":{
                "self":{"href":"/v1/companies/8113/employees/12430"},
                "company":{"href":"/v1/companies/8113"},
                "position":{"href":"/v1/companies/8113/employees/12430/position"},
                "supervisor":{"href":"/v1/companies/8113/employees/12430/supervisor"},
                "subordinates":{"href":"/v1/companies/8113/employees/12430/subordinates"},
                "clients":{"href":"/v1/companies/8113/employees/12430/clients"},
                "photo":{"href":"/v1/companies/8113/employees/12430/photo"},
                "photoContent":{"href":"/v1/companies/8113/employees/12430/photo?alt=media"}},
        "address":"7292 Dictum",
        "birthDate":"1976-01-04T23:00Z",
        "city":"San Antonio",
        "code":"EMP002",
        "country":"USA",
        "dateCreated":"2020-06-09T09:45Z",
        "dateModified":"2017-07-19T07:17Z",
        "email":"lawrence@acme.com",
        "externalId":null,
        "firstName":"LAWRENCE",
        "gender":"male",
        "hireDate":null,
        "id":12430,
        "lastName":"WISE",
        "nationalId":"",
        "phone":"1-541-754-3010",
        "phone2":"",
        "photo":153648986024067666,
        "postalCode":"47096",
        "province":""
}                        
                    
  • The _embedded attribute has a summary of each one of the objects in which the employee relates to. In this case, it includes a summary of its company data, job position and currently assigned supervisor. The rest of the objects returned by the API follow the same logic.
  • The _links attribute contains links to the resources in which the employee relates to. When the related object can exist independently, it also allows to establish or eliminate the relationship between them. In the case of an employee, the links are:
    In general, application/json is the content-type of POST requests to create and update resources, and to create and delete relations between resources, text/uri-list is used with the list of URIs (one per line) of the resources to relate. For more information, see an example to assign an administrator to 2 companies.
  • Dates are expressed in UTC format yyyy-MM-ddTHH:mmZ

› Correlation between IDs

To correlate the HRider Employees with those we have in our own system, the Employee resource incorporates the externalId attribute. If set, the employee ID in HRider can be replaced with the value given using the prefix 'external-id=' in any of the used URIs. For example, creating an employee with the attribute externalId 5678 and its ID in HRIder being 1234, these 2 calls to obtain the employee are equivalent:

curl -i -X GET 'https://dev.hrider.net/api/v1/companies/12345/employees/1234' \
        -H 'authorization: yourAuthAPIKey'



curl -i -X GET 'https://dev.hrider.net/api/v1/companies/12345/employees/external-id=5678' \ 
        -H 'authorization: yourAuthAPIKey'


This allows us to reference the employee from our system when we call the API without having to know the ID that it has in HRider.

› Navigation

The easiest way to work with the API is to navigate through the links that the API itself returns. One way to start is by getting the main anchor point that corresponds to the path to the API version (v1):

curl -i -X GET 'https://dev.hrider.net/api/v1' -H 'authorization: bearer yourAPIKey'
                    
The response obtained is:

{
    "_embedded":null,
    "_links":{
            "self":"v1",
            "companies":{"href":"v1/companies"},
            "administrators":{"href":"v1/administrators"},
            "files":{"href":"v1/files"}
    }
}
                    
The object contains the API's first level links, see that it includes in its path the same version of the API that was used in the request:
  • companies. Link to work with companies.
  • administrators. Link to work with administrators.
  • files. Link to work with files.

› Pagination

Some of the services may contain a collection of objects too large to get them all in one call. In this situation, the response is paginated with a limited number of results, and it is necessary to navigate through the rest of the pages to obtain the following objects in the collection. To navigate through the collection, page and pageSize parameters are used:

In the example case of Employees, the request:

curl -i -X GET 'https://dev.hrider.net/api/v1/companies/8113/employees?pageSize=2' \
-H 'authorization: yourAPIKey'
                    


Returns an object of the type collection with only 2 employees per page like:

{
    "total":17,
    "_embedded":{
        "employees":[ ... ]
    },
    "_links":{
        "self":{"href":"/v1/companies/8113/employees?pageSize=2&page=1"},
        "_next":{"href":"/v1/companies/8113/employees?pageSize=2&page=2"},
        "_previous":null
    }
}                        
                    

Use the link _next to navigate to the next page. Since it is the first page, the value for the _previous link is null, otherwise use it to navigate to the previous page. The total attribute indicates the total number of employees in the collection.

Errors

The API returns HTTP errors along with a JSON object that extends the error information with the attributes:
  • code. HRider internal error code
  • status. HTTP error code
  • message. Error message
  • description. Error description
The request of an object that does not exist returns an HTTP 404 (Not found) error like:
      
HTTP/2 404 
content-type: application/json
content-length: 93

{"code":"E001","status":404,"message":"Not found","description":"Employee '124301' not found"}                    
                    
The following table shows all the existing error codes with the HTTP status codes that they may contain: