1 General


You can use our web (HTTP request) API to receive employee information from HRWorks by way of a JSON formatted response.

 
1.1 Authentication

Your API calls must contain the API key for the purpose of authentication.

Parameter

Description

keyPlease contact the HRWorks administrator in your organization for the API key.

You can generate the API key for your organization yourself.

1.2 Endpoint

https://hinote.in/hrworks/api/v1/EmployeeMaster.do
You need to use https in your API call.

Please note that the API key must be appended with the URL as a request parameter.

2 Get Request

You can receive employee information from HRWorks using this request. The Get request can be made by way of an optional JSON formatted parameter called searchFilter, which allows you to seek employee data as per the following fields as input condition.

2.1 Input Fields (all fields are optional)

Field

Description

employeeId
Single employee ID or multiple employee IDs separated by space or comma.
firstName

Single employee first name. Does not accept multiple first names.

Information on all employees whose first name starts with the given value will be returned. Also, does not restrict the output to an exact match. For example, the input field value "Abdul" shall return information on employees with the first names "Abdul" and "Abdullah".

lastName

Single employee last name. Does not accept multiple last names.

Information on all employees whose last name starts with the given value will be returned. Also, does not restrict the output to an exact match. For example, the input field value "Sha" shall return information on employees with the last names "Sha", "Shah", "Sharma" and "Shailendar".

divisionIds

Single division ID or multiple division IDs separated by comma. The input should be a JSON array.

Format: ["divisionId1","divisionId2"].

designationIds
Single designation ID or multiple designation IDs separated by comma. The input should be a JSON array.

Format: ["designationId1","designationId2"].

statusIds
Single status ID or multiple status IDs separated by comma. The input should be a JSON array.

Format: ["statusId1","statusId2"].

workLocationIds
Single location ID or multiple location IDs separated by comma. The input should be a JSON array.

Format: ["workLocationId1","workLocationId2"].

employeeTypeIds
Single employee type ID or multiple employee type IDs separated by comma. The input should be a JSON array. Format: ["employeeTypeId1","employeeTypeId2"].
joinDatePeriod

Refers to employee join date as a filter. Supports the following sub-parameters:

a. fromDate

Should be in the yyyy-mm-dd format.

b. toDate

Should be in the yyyy-mm-dd format.

Note:

  • yyyy = year in 4 digits. For example, 2015.
  • mm = month in 2 digits, from 01 (for January) to 12 (for December).
  • dd = day of month in 2 digits, from 01 to 31.

c. days

Should be a number with up to 4 digits. "days" refers to the number of days in the past with reference to the current date. For example, if the API call is made on 01-Sep-2015 and the "days" value is 1000. The API call shall attempt to retrieve of all employees who joined the organization from 01-Sep-2015 to 1000 days prior,

separationDatePeriod

Refers to employee separation date as a filter. Supports the following sub-parameters:

a. fromDate

Should be in the yyyy-mm-dd format.

b. toDate

Should be in the yyyy-mm-dd format.

Note:

  • yyyy = year in 4 digits. For example, 2015.
  • mm = month in 2 digits, from 01 (for January) to 12 (for December).
  • dd = day of month in 2 digits, from 01 to 31.

c. days

Should be a number with up to 4 digits. "days" refers to the number of days in the past with reference to the current date. For example, if the API call is made on 01-Sep-2015 and the "days" value is 1000. The API call shall attempt to retrieve of all employees who joined the organization from 01-Sep-2015 to 1000 days prior,

changedSince

Refers to a date (as per ISO8601) after which new employee records or employee records which have undergone a change can be retrieved.

Typical Formats: yyyy-mm-dd hh:mm:ss or yyyy-mm-ddThh:mm:ss (see all accepted formats).

Note:

  • yyyy = year in 4 digits. For example, 2015.
  • mm = month in 2 digits, from 01 (for January) to 12 (for December).
  • dd = day of month in 2 digits, from 01 to 31.
  • hh = hour in 2 digits, from 00 to 23.
  • mm = minute in 2 digits from 00 to 59.
  • ss = second in 2 digits from 00 to 59.
  • T = Letter T can be inserted between yyyy-mm-dd and hh:mm:ss instead of space.
  • Z = Letter Z refers to zero meridian and can be appended (optional) to hh:mm:ss.

The time format represents Coordinated Universal Time (UTC). For example, 2015-09-03 13:50:00 or 2015-09-03T13:50:00Z represents 01:50 p.m. (UTC) on September 09, 2015.

Time Zones:

The strings +hh:mm+hhmm, -hh:mm, -hhmm can be appended to yyyy-mm-dd hh:mm:ss in order to specify a time zone relative to UTC. For example, UTC+5:30 represents Indian Standard Time (IST) and hence 2015-09-03 13:50:00+05:30 represents 01:50 p.m. (IST) on September 09, 2015.

Accepted date and time formats:

a. yyyy-mm-dd hh:mm:ss+hh:mm

b. yyyy-mm-dd hh:mm:ss+hhmm

c. yyyy-mm-dd hh:mm:ss-hh:mm

d. yyyy-mm-dd hh:mm:ss-hhmm

Note:

a. In all of the above, the space between yyyy-mm-dd and hh:mm:ss can be replaced with the letter T. For example, both 2015-09-30 12:00:00 and 2015-09-30T12:00:00 are acceptable.

b. In all of the above the letter Z can be appended to hh:mm:ss. Both hh:mm:ss and hh:mm:ssZ refer to time in UTC. For example, both 2015-09-30T12:00:00 and 2015-09-30T12:00:00Z refer to the same time in UTC .

A single Get API call can contain values for one or more of the above parameters.

Please note that the value of searchFilter must be URLEncoded. Also, the use of searchFilter is optional. If searchFilter is not specified, the API shall return information on all employees.

2.2 URL Format

URL format: https://hinote.in/hrworks/api/v1/EmployeeMaster.do?key=<apiKey>&searchFilter=
{
  "employeeId": "AAAA",
  //Single EmployeeId or multiple employee Ids separated by space or comma. AAAA represents some text input.
  "firstName": "AAAA",
  "lastName": "AAAA",
  "divisionIds": ["AAAA", "AAAA", "..."],
  "designationIds": ["AAAA", "AAAA", "...."],
  "statusIds": ["AAAA", "AAAA", "...."],
  "workLocationIds": ["AAAA", "AAAA", "...."],
  "employeeTypeIds": ["AAAA", "AAAA", "...."],
  "joinDatePeriod": {
                     "fromDate": "YYYY-MM-DD",
                     "toDate": "YYYY-MM-DD",
                     "days": 0000
                    },
  "separationDatePeriod": {
                           "fromDate": "YYYY-MM-DD",
                           "toDate": "YYYY-MM-DD",
                           "days": 0000
                           },
  "changedSince": "yyyy-mm-dd hh:mm:ss"
}
]

2.3 Get Employee Master Info Examples

a. https://hinote.in/hrworks/api/v1/EmployeeMaster.do?key=<apiKey>

Requests all employee data in the database as it exists at the time of the request.

b. https://hinote.in/hrworks/api/v1/EmployeeMaster.do?key=<apiKey>&searchFilter={"divisionIds":["Corporate", "Engineering"]}

Requests all employee data in the divisions with IDs "Corporate" and "Engineering".

c. https://hinote.in/hrworks/api/v1/EmployeeMaster.do?key=<apiKey>&searchFilter={"divisionIds":["Corporate", "Engineering"],"changedSince": "2016-02-01 00:00:00"}

Requests all employee data which have been newly inserted or modified on or after February 01, 2016 12 a.m and who belong to either the "Corporate" or the "Engineering" divisions.

3. Response


If the Get Employee Master Info request API call is successful, the API shall return a JSON formatted response with all the following field values.

3.1 Output Fields

FieldDescription
employeeCount
Total number of employee records in the response.

employees - Presents the details of each employee as an array with individual elements having the following fields.

employeeId
Employee ID of the employee.
firstName
First name of the employee.
middleName
Middle name of the employee. This may not be available for some or all records.
lastName
Last name of the employee. This may not be available for some or all records.
gender
Gender of the employee. M => Male, F => Female
salutation
Salutation for the employee.
nationality
Nationality of the employee.
fatherName
Name of the employee's father.
maritalStatus
Marital status of the employee. M => Married, S => Single
spouseName
Name of the employee's spouse.
bloodGroup
Blood group of the employee.
dateOfBirth

Date of birth of the employee in the yyyy-mm-dd format.

bankBranch
Bank Name and Branch name of the employee's bank account. <Bank name>/<Branch name>
bankAccountNo
Bank Account Number of the employee's bank account
nameInBankAccount
Employee's name stored in the bank records. The value shall appear only if its available
dateOfJoining
Employee's date of joining in the yyyy-mm-dd format.
groupJoinDate

In case an employee worked for a different company in the same group prior to joining the current company, the group join date can be stored. Mainly used for the purpose of gratuity calculation. The group join date is optional and can be earlier than or the same as employee's date of joining.

Value shall be in the yyyy-mm-dd format.

dateOfConfirmation
Date of employee confirmation in the yyyy-mm-dd format.
userId
HRWorks User ID assigned to the employee.
<Custom Attribute Id>

Custom attributes that are not tracked with change history are included as simple fields with the Custom attribute Id as the field name.

Custom attributes that are tracked with change history are included as fields in an array format as follows:
"<Custom Attribute Id>": [
                {
                    "fromDate": "<>",
                    "value": "<Custom Attribute Value>"
                }
            ]

dependant

Details of an employee's dependants. Presented as an array even if there is only one dependant. The parameters for each dependant are as follows.

- relationship
Relationship (spouse, son, daughter etc.) of the dependant to the employee.
- salutation
Salutation (Mr, Ms, etc.) for the employee dependant.
- firstName
First name of the employee dependant.
- middleName
Middle name of the employee dependant.
- lastName
Last name of the employee dependant.
- dateOfBirth
Date of birth of the employee dependant.
statutoryId
Details of an employee's statutory IDs.
- panPermanent Account Number of the employee.
- pfnoProvident Fund Account number of the employee.
- esinoEmployee State Insurance account number of the employee.
- uanUniversal Account Number of the employee.
- <Custom Statutory Id>Each additional custom statutory id created in HRWorks shall be listed here.


manager

Returns an array with all the historical information (employee ID and from date)

Format: [{fromDate: "", "employeeId:""}]

payPackage

Compensation package of the employee. Returns an array with historical data.
 "payPackage": [
                {
                    "fromDate": "<>",
                    "compensationDetails": {
                        "hopId1": "<amount>",
                        "hopId2": "<amount>",
                        "hopId3": "<amount>",
                        "variable HopId": "Configured" -- For variable head of pay, value will be Configured
                    },
                    "deductionDetails": {
"hodId1": "<amount>",
                        "variable HodId": "Configured" -- For variable head of deduction, value will be Configured
                    }
                }
            ]

employeeType

Employee type value. For example, "PM" for Permanent. Returns an array with historical data.
"employeeType": [
                {
                    "fromDate": "<>",
                    "id": "<Employee Type Id>"
                }
            ]

designation

Designation of the employee. Returns an array with historical data.
"designation": [
                {
                    "fromDate": "<>",
                    "id": "<Designation Id>"
                }
            ]

status

Status of the employee. Returns an array with historical data.
"status": [
                {
                    "fromDate": "<>",
                    "id": "<Employee Status Id>"
                }
            ]

division

Name of the division to which the employee is assigned. Returns an array with historical data.
"division": [
                {
                    "fromDate": "<>",
                    "id": "<Division Id>"
                }
            ]

workLocation

Work location of the employee. Returns an array with historical data.
"workLocation": [
                {
                    "fromDate": "<>",
                    "id": "<Location Id>"
                }
            ]

contactAddress

Contact address of the employee. Returns an array.

"contactAddress": [
{
"addressType": "",
"addressLine1": "",
"addressLine2": "",
"city": "",
"state": "",
"postalCode": "",
"country": "",
"isPrimary": <>
}
]

contactEmail

Email ID of the employee. Returns an array.

"contactEmail": [

{
"emailType": "",
"emailId": "",
"isPrimary": <>
}
]

contactNo
Contact number of the employee. Returns an array.

"contactNo": [

{

"phoneType": "",
"phoneNo": "",
"isPrimary": <>

}
]

The output shall contain employee records of all the above fields. If you have no need for any of the fields, you can ignore the field and its value while processing the output. 

3.2 Response in case of error


In case of error, the API returns the following JSON response:


{
    "success": false,
    "statusCode": <>,
    "errorMsg": <>
}

 
Note:

  1. errorMsg is a string value describing the error. 
  2. Status codes are described in the Status Codes section.


4 Coding Examples

4.1 CURL


1
2
3

#The following command returns employee data in response
  
curl --location --request GET 'https://hinote.in/hrworks/api/v1/EmployeeMaster.do?key=<apiKey>&searchFilter=%7B%22employeeId%22:%22<EmployeeId>%22%7D'

  • No labels