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 -
email 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
email 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
  • JSON
  • XML
  • 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.
  • JSON
  • XML
  • 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.
  • JSON
  • XML
  • 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
  • JSON
  • XML
  • Request:

    Response:

    Request:

    Response:

    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.
  • JSON
  • XML
  • Request:

    Response:

    Request:

    Response: