Handling New Hire Round-Tripping

When processing New Hires in WFH, it is important to understand the New Hire Round Trip process. WFH will create a “New Hire” account for each onboarded employee. The incoming employee will log into WFH with this New Hire account and complete the Onboarding process which includes providing employee information, and reviewing and signing employment documents, etc. At the end of this process, WFH will generate a unique newHireId for the onboarded employee and add the New Hire change type to the pending changes queue. The New Hire account is still active, but it cannot be used to log into WFH until the employee is Round-Tripped.

Round-Tripping is accomplished by creating a new Employee in the payroll system, and then syncing that Employee back to WFH using the Upsert Employee route.  You must include the unique newHireId the first time you sync this Employee back to WFH. When WFH sees an incoming Employee with a newHireId, it will associate that Employee with the WFH new hire account created during the onboarding process and will convert the new hire account into a regular WFH Employee account.

The following process describes how to properly link New Hire records created during onboarding to an employee in WFH:

1. The client creates a New Hire and goes through the onboarding with the employee.
2. You call into WFHAPI to the Get ESS Pending Changes route and get the new hire. This gives you the changeId and the newHireId
3. Using the newHireId you get the details about the new hire from the Get ESS New Hire route.
4. You add the employee on your end using the details just retrieved in Step 3 then call the WFHAPI Acknowledge ESS Change route with the changeId retrieved in Step 2 to let WFH know that you got the new hire details and added the new hire to your system.
5. Finally, you call into the WFH API Upsert Employee route, and send in that newHireId in the fields object (along with any other data you are sending). The payload for that looks something like this (you may send other fields too, this would just be the bare minimum):

{ 
  "employeeCode": "1000",
  "companyId": 1234,
  "partnerId": 1234,
  "firstName": "Testing",
  "lastName": "Testing",
  "email": "email@example.com",
  "fields": {
    "newHireId": "AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE"
  },
  "originalHireDate": "01/01/2024" 
}

Note that the newHireId only needs to be sent on the initial creation of the employee to link it. And in fact, if you send it in a subsequent employee sync, it would be ignored.  You cannot link a new hire record to an existing employee, it can only be linked upon employee creation.