benefitsEZ API Reference
Overview
benefitsEZ API provides employers another means to integrate their master sources of Employee information. This can be their Payroll system, or HR Administration system or an ERP system. Employers have to register and establish their account gaining identity in the benefitsEZ site. Once this is done, employers can write a program in the language of their choice to invoke benefitsEZ API supplying the same credentials.
benefitsEZ platform is built entirely with a Services Architecture that allows virtually every operation and data access through a secured API. Initially, we have opened up the Employee related information for API access.
You can use the API to load initial employee census data, or forward changes as they happen in your Payroll or HR system. The API invocation has exactly the same impact as the employer using the Portal.
In this, you will find a Sample Company - Model Account Enterprises setup with about 300 employees and 500 dependents to a total of about 800 covered lives. You can get a feel of how the API works and how easy to integrate with your data. You can perform data operations on employees, search on employee data and retrieve them. API allow the use of JSON or XML data as the input and output. Although benefitsEZ Services Architecture allows for GET, POST and DELETE operations, we have suggested mostly POST operations here.
If you are more interested to know about the API, or have particular requirements about API, please send us a email to info@hitef.com , we will be happy to open up more of our API access to you.
Note that certain validation conditions have been relaxed intentionally for this sample API demo purposes.
Authentication
We provide JWT Token Authentication for API. You can obtain a token by supplying your established account credentials in this page. All subsequent operations use this token to authenticate to the benefitsEZ API. We have pre-initialized with the model-account admin user credentials in this page. You should click Authorize first , to authenticate yourself as a model-account user and try API operations. Alternately, you can change them to use your own credentials and interact with your account data.
Employees
Employees of the employer who are considered for the Employer Sponsored Insurance Benefits. Employees defined here are subject to employer defined eligibility rules, benefit contribution strategy rules. Employees are also created as users of benefitsEZ gaining access to Employee Experience, if the Employer has turned ON Employee Identity Switch in the Employer's account profile
Create or modify an employee
This method creates a new employee record or modifies an existing employee record. Whether the given record is New or existing one in benefitsEZ is based on the employee's firstName, middleName and lastName. Name changes of existing employees must b submitted through Life State Change Operations Method in the Change Function.
Element | Description | Format | Mandatory | Valid values |
---|---|---|---|---|
firstName | First Name | String | true | |
middleName | Middle Initial or Name | String | false | |
lastNmae | Last Name | String | true | |
nickName | Nick Name | String | false | |
dob | Date of Birth | Date | true | less than 80 years old |
gender | Gender | String | true | M,F,Male,Female |
SSN | Social Security Number | String | false | 9 digits with or without - |
Work Email Address | Email address format | false | ||
homeAddress | Full Home Address in one line | Valid U.S. Address in one line, e.g. 45 Francis Street, Boston, MA 02115 | false | |
addressLine1 | Address Line1 | e.g. 45 Francis Street | false | |
addressLine2 | Address Line2 | e.g. Apt # 450 | false | |
city | City | Boston | false | |
state | State | 2 digit State code e.g. MA | false | 2 character U.S. State |
zipCode | 5 digit zip code | U.S. Postal Zip code | false | |
employeeCode | Internal code or Identifier used by Employer | String | false | |
employeeType | Type of Employee | String | false | Fulltime,Parttime,Temporary,1099 Contractor,Retiree |
department | Department in which Employee works | String | false | Sales,Marketing,Legal,Finance,Human Resources,Engineering,Product,Corporate Development,Customer Service |
employeeGrade | Employee's Grade | String | false | Has to be one of the values defined in the Employer Account Profile |
location | Employer location | String | false | Has to be one of the values defined in the Employer Account Profile |
hoursWorkedPerWeek | Weekly Hours worked by the employee, default is 40 | Integer | false | |
originalDateOfHire | 5 digit zip code | Date | false |
Element | Description | Format |
---|---|---|
id | benefitsEZ Unique Identifier for Employee | Number |
firstName | First Name | String |
middleName | Middle Initial or Name | String |
lastNmae | Last Name | String |
nickName | Nick Name | String |
fullName | Full Name | String |
dob | Date of Birth | Date |
gender | Gender | String |
SSN | Social Security Number | String |
Work Email Address | Email address format | |
homeAddress | Full Home Address in one line | Valid U.S. Address in one line, e.g. 45 Francis Street, Boston, MA 02115 |
addressLine1 | Address Line1 | e.g. 45 Francis Street |
addressLine2 | Address Line2 | e.g. Apt # 450 |
city | City | Boston |
state | State | 2 digit State code e.g. MA |
zipCode | 5 digit zip code | U.S. Postal Zip code |
employeeCode | Internal code or Identifier used by Employer | String |
employeeType | Type of Employee | String |
department | Department in which Employee works | String |
employeeGrade | Employee's Grade | String |
location | Employer location | String |
hoursWorkedPerWeek | Weekly Hours worked by the employee, default is 40 | Integer |
originalDateOfHire | 5 digit zip code | Date |
createdInfo | Which benefitsEZ user created this record and When | String |
lastUpdatedInfo | Which benefitsEZ user last updated this record and When | String |
versioNo | How many times the record is modified since creation | Number |
Request:
Response:
Request:
Response:
Create or modify one or more employees
This is a bulk method that can handle creation or modification of employee records collectively given. This follows the same data structure as creating (or modifying) an employee but submitted in a list
Element | Description | Format | Mandatory | Valid values |
---|---|---|---|---|
EmployeeList | Employee List Wrapper acting as XML Root. In case of JSON, it is a JSON array | List | true | |
Employee Record | Record structure of Employee as defined in the Create or Modify Request of an employee, repeated as many times as the bulk change is needed |
Element | Description | Format |
---|---|---|
EmployeeList | Employee List Wrapper acting as XML Root. In case of JSON, it is a JSON array | List |
Employee Record | Record structure of Employee as defined in the Create or Modify Response of an employee, repeated as many of those submitted records that got processed succesfully. |
Request:
Response:
Request:
Response:
Find employee
Finds employee by id ot full name
Element | Description | Format | Mandatory | Valid values |
---|---|---|---|---|
id | List | true | ||
full name |
Element | Description | Format |
---|---|---|
Employee Record | Record structure of Employee as defined in the Create or Modify Response of an employee, repeated as many of those submitted records that got processed succesfully. |
Request:
Response:
Request:
Response:
Delete one or more existing employees
This method deletes an employee record, subject to constraints that employee record can be deleted only prior to certain steps in the Benefits Lifecycle. Deletion is also not possible of an employee who has ever been enrolled or secured benefits in the past coverage years. Deleting an employee record will remove any user identity and login established by the employee in benefitsEZ and other related information such as eligibility records etc. Note that deletion may happen in a slightly delayed manner as it is as an asynchronous operation.
Element | Description | Format | Mandatory | Valid values |
---|---|---|---|---|
employeeIds | Comma Separated benefitsEZ Employee Ids of those who need to be deleted | String | false | Valid Numbers recognized as benefitsEZ employee Identifiers of the authorized employer |
fullName | Full Name of the employee who needs to be deleted | String | false | |
employeeCode | Employer's internal employee code mapped to benefitsEZ | String | false |
Element | Description | Format |
---|---|---|
processMessage | Message suggesting the employee records have been deleted or initiated for deletion | String |
Request:
Response:
Request:
Response:
Employee Search
Parametric Search of Employee Record data, submitted as a Search Criteria and returned as a List of Employee Records
Element | Description | Format | Mandatory | Valid values |
---|---|---|---|---|
Id | Employee - Object that is being searched | String | true | Employee |
FilterAttribute | Simple Filter - Attribute or Property of Employee that is being searched on with operator and value. e.g.- lastName ENDS Peterson alternately lastName=Peterson% e.g.- location=Boston. Complex Filter - Can be a ORFilter or ANDFilter too | SearchFilterAttribute | false | Should use a valid property name of Employee object |
ANDFilter | Collection of one or more SearchFilterAttribute. e.g. to obtain all Female Employees based out of Boston location - give the string : gender=Female,location=Boston | SearchFilterAttribute | false | Should use a valid property name of Employee object |
ORFilter | Collection of one or more SearchFilterAttribute. e.g.to obtain all employees who belong to Executive OR Senior Manager Grades - give the string : employeeGrade=Executive,employeeType=Senior Manager | SearchFilterAttribute | false | Should use a valid property name of Employee object |
Element | Description | Format |
---|---|---|
EmployeeList | Employee List Wrapper acting as XML Root. In case of JSON, it is a JSON array | List |
Employee Record | Record structure of Employee as defined in the Create or Modify Response of an employee, repeated as many of those submitted records that got processed succesfully. |
Request:
Response:
Request:
Response: