...
Your API calls must contain the API key for the purpose of authentication.
Parameter | Description |
|---|---|
| key | Please contact the HRWorks administrator in your organization for the API key. |
You can generate the API key for your organization yourself.
...
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:
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:
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:
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
|
2.3 Get Employee Master Info Examples
...
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
| Field | Description |
|---|---|
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: |
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. |
| - pan | Permanent Account Number of the employee. |
| - pfno | Provident Fund Account number of the employee. |
| - esino | Employee State Insurance account number of the employee. |
| - uan | Universal 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. |
employeeType | Employee type value. For example, "PM" for Permanent. Returns an array with historical data. |
designation | Designation of the employee. Returns an array with historical data. |
status | Status of the employee. Returns an array with historical data. |
division | Name of the division to which the employee is assigned. Returns an array with historical data. |
workLocation | Work location of the employee. Returns an array with historical data. |
contactAddress | Contact address of the employee. Returns an array. "contactAddress": [ |
contactEmail | Email ID of the employee. Returns an array. "contactEmail": [ { |
contactNo | Contact number of the employee. Returns an array. "contactNo": [ { "phoneType": "", } |
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.
...
In case of error, the API returns the following JSON response:
|
Note:
- errorMsg is a string value describing the error.
- Status codes are described in the Status Codes section.
4 Coding Examples
4.1 CURL
1 |
|