API Upgrades

The versions on this page represent breaking changes that we have made to our API since January 2021. The definition of a breaking change is one that causes some code that was written against a prior version of our API to break in the new version. Breaking changes are most commonly caused by either removing or renaming existing fields in the API, or by making a field required that was previously not required. We do not consider adding new endpoints or new fields to existing endpoints breaking changes. For more information on how to use a specific version of our API, please see our page on Versioning.

We release new code, functionality, tests, and other features to the Check API many times per day. However, we do our best in our power to minimize the number of breaking changes that we release to Check's APIs. This is because we want to avoid forcing our customers to change their code to benefit from new features that we've launched to our system. We publish all new changes and features that we release to our product on our Changelog.

Check considers the following changes to be backwards-compatible:

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Adding new forms.
  • Changing the order of properties in API response objects.
  • Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings. This includes adding or removing fixed prefixes (such as emp_ on employee IDs). You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length.
  • Adding new webhook event types. Your webhook listener should gracefully handle unfamiliar event types.

2023-04-04

  • The amount field on net pay split objects is now optional instead of required. We have added a percentage field, and one of amount or percentage must be specified.
{
  "splits": [
    {
      "bank_account": "<string>",
      "priority": 1,
      "percentage": 20.0
    },
    {
      "bank_account": "<string>",
      "priority": 1,
      "percentage": 80.0
    }
  ],
  "employee": "<string>",
  "contractor": "<string>",
  "is_default": false
}

2021-09-02

  • The datatype of the approval_deadline field returned on a payroll is now datetime rather than date
  • When creating a post-tax deduction with a type of child_support, the related employee must now have a ssn
  • JSON structure of payroll item warnings has been updated to provide more detail and support additional deduction types
{
  "id": "pay_DqU6bDyZCei6lwN9Htty",
  "items": [
    {
      "id": "itm_oSqBwnwoYPWrEJbZ4Sph",
      "earnings": [
        {
          "amount": "4000.00"
        }
      ],
      "post_tax_deductions": [
        {
          "amount": "1444.39",
          "post_tax_deduction": "ptd_rpW8oqIUdMF33f4Yx2Ui"
        }
      ],
      "warnings": [
        {
          "code": "partially_applied",
          "post_tax_deduction": "ptd_rpW8oqIUdMF33f4Yx2Ui",
          "reason": "exceeds_max_percent"
        }
      ]
    }
  ]
}
{
  "id": "pay_DqU6bDyZCei6lwN9Htty",
  "items": [
    {
      "id": "itm_oSqBwnwoYPWrEJbZ4Sph",
      "earnings": [
        {
          "amount": "4000.00"
        }
      ],
      "post_tax_deductions": [
        {
          "post_tax_deduction": "ptd_rpW8oqIUdMF33f4Yx2Ui",
          "amount": "1444.39"
        }
      ],
      "warnings": [
        {
          "code": "partially_applied",
          "reason": "exceeds_max_percent",
          "deduction_type": "post_tax_deduction",
          "deduction": "ptd_rpW8oqIUdMF33f4Yx2Ui",
          "actual_deduction_amount": "1444.39",
          "expected_deduction_amount": "10000000.00"
        }
      ]
    }
  ]
}

2021-04-08

  • amount on earnings and reimbursements for payroll items is now required to be greater than $0.00
  • JSON structure and design of paystub endpoint has been updated to return a breakdown of current earnings in the period
{
  "payroll": "pay_GEESILnTURN8QDch1HmR",
  ...
  "earnings": [
    {
      "type": "Non-hourly regular",
      "code": null,
      "earning_code": null,
      "amount": "97.00",
      "amount_ytd": "97.00",
      "hours": null,
      "hours_ytd": null,
      "piece_units": null,
      "piece_units_ytd": null,
      "description": "Non-hourly regular",
      "rate": null
    },
    {
      "type": "Bonus",
      "code": null,
      "earning_code": null,
      "amount": "41.00",
      "amount_ytd": "41.00",
      "hours": null,
      "hours_ytd": null,
      "piece_units": null,
      "piece_units_ytd": null,
      "description": "Bonus",
      "rate": null
    }
  ]
}
{
  "payroll": "pay_GEESILnTURN8QDch1HmR",
  ...
  "earnings": [
    {
      "type": "Non-hourly regular",
      "code": null,
      "earning_code": null,
      "amount": "97.00",
      "amount_ytd": "97.00",
      "hours": null,
      "hours_ytd": null,
      "piece_units": null,
      "piece_units_ytd": null,
      "name": "Non-hourly regular",
      "current_earnings": [
        {
          "description": "Non-hourly regular",
          "amount": "97.00",
          "hours": null,
          "piece_units": null,
          "workplace": "wrk_f0iPsbipPysvFyXVuJcD",
          "rate": null
        }
      ]
    },
    {
      "type": "Bonus",
      "code": null,
      "earning_code": null,
      "amount": "41.00",
      "amount_ytd": "41.00",
      "hours": null,
      "hours_ytd": null,
      "piece_units": null,
      "piece_units_ytd": null,
      "name": "Bonus",
      "current_earnings": [
        {
          "description": "Bonus One",
          "amount": "11.00",
          "hours": null,
          "piece_units": null,
          "workplace": "wrk_f0iPsbipPysvFyXVuJcD",
          "rate": null
        },
        {
          "description": "Bonus Two",
          "amount": "13.00",
          "hours": null,
          "piece_units": null,
          "workplace": "wrk_f0iPsbipPysvFyXVuJcD",
          "rate": null
        },
        {
          "description": "Bonus Three",
          "amount": "17.00",
          "hours": null,
          "piece_units": null,
          "workplace": "wrk_f0iPsbipPysvFyXVuJcD",
          "rate": null
        }
      ]
    }
  ]
}

2021-02-16

  • When approving a payroll, the related company must have a phone

2021-01-15

  • Introduced API versioning