Syncing Employees

Are We Talking About The Same People?

You have successfully integrated via OAuth, gotten back the authenticated
company for the current user, and fetched the company's employees.

Now you have the JSON representation of 20 employees and need to map them to the employees in your database.

Naturally, the approach you'll choose will depend on the information you have available. Here are some suggestions for matching up the employees in your database with the ones in ours. We recommend persisting the unique uuid attribute that is returned by the API, rather than redoing the match at the beginning of a pay period. We require employee reconciliation leverages at least two data points when reviewing integrations for production access and typically recommend the following as reliable fields for said reconciliation:

Email Addresses

We provided email addresses with employee information specifically for matching employees between systems. Every onboarded employee will have at minimum a personal email address associated and some will also have a work email address. We recommend you compare both against your records to increase the odds of finding a match.

Date of Birth

We recommend matching against year, month, and day and caution against only comparing month and day, as it takes only 57 people to achieve a 99% probability of collision.

Full Name

First and last names are required for employees in the Gusto system. Typos do happen, in which case checking the Hamming Distance can be helpful. If you have one unmatched set of employees with a Hamming Distance of 1, for example, it is pretty likely that they are the same person.

Matching against two of the three criteria above will provide a reasonable balance between maximizing successful matches, while minimizing mismatches.

Common Questions

What is the value of syncing employees between our platform and Gusto?

Employee sync is a tremendous value add as it allows users to easily onboard new staff members in either system, simplifying their workflows and saving them time. This reliable and quick sync of staff info between the two systems creates a more robust product offering leading to additional customer adds

What is employee reconciliation? Why do you require that employees be matched between the two systems?

Employee reconciliation is the ability to match the same employees between your system and Gusto. We require that employees be matched based on at least 2 criteria to ensure we are talking about the same people (email address, date of birth, or full name).

Why do you require the ability for user’s to manually match or review the employee reconciliation done by the API in the UX?

This allows users to confirm the right people are matched and make changes, ignore, or create based on what the integration originally suggested. We’ve found that this cuts down on the number of errors and drastically improves the user experience.

Once an employee is created in Gusto via the API, what happens next?

Once an employee is created, a company admin can complete their onboarding via People --> Team Members --> Onboarding. Onboarding must be completed prior to paying an employee through Gusto since we need specific information to process payroll (e.g W-4 tax info and payment preferences).