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
orinclude_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.
- Payrolls can now be previewed asynchronously. This is enabled by setting the flag
- 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
status_change
webhook event type was deprecated.
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 apercentage
field, and one ofamount
orpercentage
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 nowdatetime
rather thandate
- When creating a post-tax deduction with a
type
ofchild_support
, the related employee must now have assn
- 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