January 15, 2021
January 8, 2022

API versioning

Alex DelVecchio
January 15, 2021
January 8, 2022

API versioning

Alex DelVecchio

With any rapidly evolving API like Check’s, occasionally breaking changes need to be made. Up until now, we've dealt with this by closely coordinating with each of our Partners to ensure that they have made the necessary changes on their end before we release any breaking change. However, we've known that this was not a scalable solution for any party.

To solve these issues, we're happy to announce that the Check API is now versioned. This means that going forward, we will periodically release one or more breaking changes as a new API version, and each Partner can choose to adopt the new version at their own pace. We will also be recording each version and the changes associated with it in our new API Changelog as they are released.

Breaking Changes

We define a breaking change as any change which has the potential to result in unexpected behavior or errors being returned from API requests that work as expected before the change.

A few examples of changes we would consider to be breaking changes:

  • Adding a required request parameter
  • Changing a request parameter from optional to required
  • Removing a request parameter
  • Removing a field from a response body
  • Adding a validation rule to a request parameter

Conversely, we would not consider these changes to be breaking changes:

  • Adding an optional request parameter
  • Adding a new API endpoint
  • Adding a field to a response body
  • Changing the ordering of fields within a response body
  • Removing a validation rule from a request parameter

Naming Convention

The naming convention for our API versions will be to name each version using the ISO-8601 date on which the version was released.

What this means is that we now accept a header named Check-Version with all requests made to the Check API. Clients can set this on their request to have it be handled by a specific version of the API.

We also now keep track of a default API version per Partner, which allows requests from that Partner to use a certain API version by default if no version is included with the request via the Check-Version header. The default API version for each Partner is initially set to the most recent API version available when their account is created in our system. If a Partner would like to change their default API version, today they can reach out to our support team, but we also plan on adding a self-serve option for that soon!

Sandbox vs. Live

We support setting different default API versions for our sandbox and live environments, so Partners can choose to change them independently from one another.

More from the Check blog

January 6, 2022
January 8, 2022

Banking Holiday Payroll Considerations

There are over a thousand holidays in the US. Whether it’s National Pet Day or National Pie Day, there is something special to celebrate everyday of the year. However, there are 11 standard Federal reserve bank holidays which hold a little more importance than the others. While for most people these holidays are an opportunity to honor special events and people, in the payroll space they represent some challenges since payroll cannot be processed on these days.
December 29, 2021
January 8, 2022

December Changelog

December's additions and updates to Check. Changes include: launch of Run Payroll Component, Support for 'Applied for' parameters, edit support for child support remittances, and more!
December 1, 2021
January 8, 2022

November Changelog

November's additions and updates to Check. Changes include: bank account verifications, FEIN validation, multiple same-type benefits support, and effective dated tax withholding settings in Console.