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.

2025-01-01

Support for large payrolls in Payroll API

Payrolls with up to 1,500 payroll items and contractor payments can now be processed in Payroll API. In previous versions, this limit was 500 payroll items and contractor payments.
New options and requirements were added to Payroll API to support the increased limit :
- Payrolls can now be previewed asynchronously. This is enabled by setting the flag async=true on the payroll preview request. Asynchronous preview is required if the payroll contains more than 500 payroll items and contractor payments.
- Payrolls will now no longer list payroll items and contractor payments by default. This can be optionally enabled by setting the flags include_items=true or include_contractor_payments=true. This option is not available if the payroll has more than 500 payroll items and contractor payments.
- Payrolls must be previewed before they can be approved.
A new property was added to the Payroll object, preview, which contains a status and a timestamp of the most recent preview calculation.

New Payroll Webhook Event Type: updated

Note: This change only applies if your default API version is set to 2025-01-01. If you wish to update our default API version, please reach out to Check.

A new payroll webhook event type, updated was updated.
The payroll status_change webhook event type was removed.

Other

The previous_payroll_provider property on the Enrollment Profile has been updated from a string input field to an enum.
A new previous_payroll_provider_other property was added to the Enrollment Profile, which accepts a free-form string to indicate other previous payroll providers not included in the enum for the above property.
Errors when setting the processing period on a Payroll have been updated from 403 Forbidden to 400 Bad Request.

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

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