Embedded Setup data sync guide

Embedded Setup is a service in which Check’s team of payroll experts take on the difficult parts of switching payroll providers, including all data migration, auditing and balancing, to seamlessly and accurately get employers ready to power their next payroll on your platform.

For a complete, high-level guide to this service, please head to our Embedded Setup Guide.

The purpose of this guide is to walk through the data synchronization requirements that you and your team will need to meet to effectively leverage Embedded Setup.

Note: Data synchronization (data sync) is critical to implement for both Full Service and Self Service Embedded Setup.

Data sync is the technical process by which two independent systems can keep their data consistent, regardless of the fact that the data can be updated separately in each of those systems.

For example: within Check’s system, we have an Employee database table where we store all the data fields relevant to the Employee object. Within the Partner’s system, you will almost always have your own independent Employee database table, where you store all data fields relevant to the Employee object in you application.

Some of these fields will overlap, and some of them won’t. That’s perfectly OK!

The goal of data sync is to keep common fields on common objects in sync with each other across the Partner’s and Check’s system. This ensures that we both operate on a consistent view of employer and employee data.

Let’s imagine a Check Partner who builds a feature that lets an employer track their employees’ favorite colors. Here’s what a side-by-side comparison of the Partner’s Employee database record might look like, compared to Check’s Employee database record, in terms of the fields each party stores on its employee record.

When an employer uses the Partner’s application to update their employee’s favorite color, that change does not need to be synchronized to Check, because Check does not know about or track that field.

However, when an employer uses the Partner’s application to update their employee’s first name, that change does need to be synced to Check, because Check will put that employee’s first name on their W-2, and important tax filings, at various points throughout the year.

In order to mechanically perform data sync in this case, the Partner should use Check’s API to send data updates it receives in its application to Check. When Check receives the API call, we will update the data accordingly on our side.

Conversely, if an employer or other user were to update the first name of an employee in Check’s system, that change also needs to be synchronized to the Partner application. In order to perform this update, we recommend that the Partner listen to webhooks that are emitted by Check about any updates made to the objects in our system.

Below is a diagram outlining this.

In order to integrate correctly with Embedded Setup, you must be able to support Check creating, updating, and deleting the following objects of the system:

This means that the bi-directional sync diagrammed above should be set up for all of the above objects. Note: you only need to bi-directionally sync these objects if you elect to store them in your database. Also, if you store an object in your database, you do not need to store all of its fields in your database — you can instead elect to store a subset of fields for that object. For some objects and fields, it is perfectly reasonable to omit them from your database, and allow Check to be the source of truth for the data. However, it is very rare for Partners to make Check the source of truth for all of the above objects. At minimum, Employees are most commonly duplicated across systems due to their centrality to the data model.

The reason why data sync is required for Embedded Service setup is that our team of payroll experts (or your customers themselves) will be creating these objects in Check's system when they go through the process of uploading historical payroll data from the customer’s previous payroll provider. Without the ability to do this in a seamless way that will enable the customer to access the data within the Partner’s application, the promise of Embedded Setup cannot be met.

As a Check Partner, you have choice in how you go about building your integration with Check. We generally work with two types of platforms:

Webhooks are the industry gold standard for implementing Data Sync. There are two reasons for this:

However, if your team cannot implement webhooks for some reason, the other option to implement data sync is polling.

In a polling strategy, the Partner issues periodic API requests to Check to check if anything has changed about the objects in the system. For example, if there are 100 employees on payroll tracked across the Partner and Check’s system, the Partner may elect to send 100 GET requests (one for each employee) every hour, to see if anything about the employees have changed on Check’s side. The majority of these requests will yield no change, and thus are wasted resources. But in the case where a change is detected, the system making the API request can persist that change on the Partner’s side.

One additional downside of polling to note is that it runs the risk of causing Partners who implement it to trigger Check’s standard rate limiting policies. By default, Partners can make 25 requests per second to the API. If your implementation of polling causes your system to make more than this number of requests, you may see 429 error codes. These requests would then need to be retried.