Defining Benefits

Benefits represent payroll contributions from employees and/or employers, with defined taxability at the federal, state, and, at times, local level. For example, benefits may include both employee and employer contributions to a health insurance account, or employee contributions to a Roth 401(k) retirement account. In some cases, contributions to a 401(k) are treated as pre-tax, whereas contributions to a Roth 401(k) account are always treated as post-tax.

There are two types of benefits: company-level and employee-level. Company-level benefits represent a benefit that a company offers to employees, while employee-level benefits represent a benefit tied to an employee. Employee benefits can be standalone or tied to a company benefit.

When modeling out benefits, it may make sense to consider what benefits can be modeled at the company level first, then create the remaining as standalone employee benefits. Inheriting from a company-level benefit allows for an easier implementation process and easier benefit administration moving forward. For example, during the process of implementing a new company, modeling a benefit at the company level allows for a single benefit type and description to apply to all employee benefits that inherit from it. In addition, the effective dates on a company benefit affect the effective status of child employee benefits, which can be helpful during benefit migration. If a company wanted to migrate providers for a specific benefit like a 401k, they could mark the effective_end on the company benefit for the old benefit, which would serve as the effective_end for all active employee benefits inheriting from that company benefit.

Employee benefits

Use the Benefits API to create and configure benefits for your employees. The following fields are available:

effective_start: The date this Benefit will be considered effective. Payrolls with a payday before this date will not include the Benefit.
effective_end (optional): The date this Benefit will no longer be considered effective. Payrolls with a payday after this date will not include the Benefit.
period: The period over which a period amount is distributed. Can be “monthly” or null. See the Period Benefits guide for more information.
company_contribution_amount: How much the company will contribute toward this employee benefit every payroll. Valid input is a dollar amount represented as a string, such as “100.23” for “$100.23”.
company_contribution_percent: How much the company will contribute toward this employee benefit every payroll, expressed as a percentage of employee earnings. Percentage-based contributions are always a percentage of the payroll item's gross total. Valid input is the percentage as a float, such as “8.5” for “8.5%”.
company_period_amount: How much the company should contribute towards this employee benefit across a period, expressed as a dollar amount, such as “100.23” for “$100.23”. See the Period Benefits guide for more information.
employee_contribution_amount: How much the employee will contribute from their paycheck toward this employee benefit every payroll. Valid input is a dollar amount represented as a string, such as “100.23” for “$100.23”.
employee_contribution_percent: How much the employee will contribute from their paycheck toward this employee benefit every payroll, expressed as a percentage of employee earnings. Percentage-based contributions are always a percentage of the payroll item's gross total. Valid input is the percentage as a float, such as “8.5” for “8.5%”.
employee_period_amount: How much the employee should contribute towards this employee benefit across a period, expressed as a dollar amount, such as “100.23” for “$100.23”. See the Period Benefits guide for more information.
hsa_contribution_limit (optional): The contribution limit for a HSA Benefit. Only applicable for Benefits of type hsa and must be either “single” or “family”. Default is “single”.

Note: Benefits must be configured for a payroll before that payroll is run, or they will not be applied.

Validations

Specifying more than one of company_contribution_amount, company_contribution_percent, and company_period_amount is not allowed. This is also true for employee_contribution_amount, employee_contribution_percent, and employee_period_amount. Company and employee period amounts cannot be set if the period field is not set. Furthermore, contribution amount and percent fields cannot be set if the period field is set.

An employee benefit can either inherit from a company benefit, or be standalone. In the case of a standalone employee benefit, the benefit type is defined on the employee benefit. However, in the case of an employee benefit that inherits from a company benefit, the benefit type on the employee benefit is pulled from the company benefit it inherits from.

See Types of benefits in the Check API documentation for the list of supported benefit types. Each benefit type has a limit on the amount that may be contributed during a given year. Check will automatically track the contribution limits of these benefit types, and reduce the benefit contributions calculated on payrolls so that benefits are no longer contributed to once the limit has been reached.

Company benefits

Use the Benefits API to create and configure benefits for your companies. The following fields are available::

effective_start: The date this benefit will be considered effective. Payrolls with a payday before this date will not include the benefit.
effective_end (optional): The date this benefit will no longer be considered effective. Payrolls with a payday after this date will not include the benefit.
period: The period over which a period amount is distributed. Can be “monthly” or null. See the Period Benefits guide for more information.
company_contribution_amount: The default value for company_contribution_amount for newly created employee benefits that inherit from this company benefit. This value can be overridden on an employee benefit. Valid input is a dollar amount represented as a string, such as “100.23” for “$100.23”.
company_contribution_percent: The default value for company_contribution_percent for newly created employee benefits that inherit from this company benefit. This value can be overridden on an employee benefit. Valid input is the percentage as a float, such as “8.5” for “8.5%”.
company_period_amount: The default value for company_period_amount for newly created employee benefits that inherit from this company benefit. This value can be overridden on an employee benefit. Valid input is a dollar amount represented as a string, such as “100.23” for “$100.23”. See the Period Benefits guide for more information.
employee_contribution_amount: The default value for employee_contribution_amount for newly created employee benefits that inherit from this company benefit. This value can be overridden on an employee benefit. Valid input is a dollar amount represented as a string, such as “100.23” for “$100.23”.
employee_contribution_percent: The default value for employee_contribution_percent for newly created employee benefits that inherit from this company benefit. This value can be overridden on an employee benefit. Valid input is the percentage as a float, such as “8.5” for “8.5%”.
employee_period_amount: The default value for employee_period_amount for newly created employee benefits that inherit from this company benefit. This value can be overridden on an employee benefit. Valid input is a dollar amount represented as a string, such as “100.23” for “$100.23”. See the Period Benefits guide for more information.

Validations

Benefit Limits for 2024

Benefit	Employee Limit	Combined Total (Employee + Employer)	Catch Up
HSA	$4,150 (Single) $8,300 (Family)	$4,150 (Single) $8,300 (Family)	$1,000
Dependent Care FSA	$5,000	$5,000	N/A
SIMPLE IRA	$16,000	N/A	$3,500
401K	$23,000	$69,000	$7,500
457	$23,000	$23,000	$7,500*
403B	$23,000	$69,000	$7,500
Roth 401K	$23,000	$69,000	$7,500
Roth 457	$23,000	$23,000	$7,500*
Roth 403B	$23,000	$69,000	$7,500

Our system automatically allows additional, catch-up contributions to HSA and retirement plans for employees who will reach the catch-up age during the calendar year of the contribution.

*457 plans may allow a special catch-up contribution for eligible employees if permitted by the plan.

Overlapping benefits of the same type

Employees are limited in the amount of benefits that they can have active with overlapping dates of the same type. This limit depends on the type of benefit. All Section 125 Benefits are limited to 10 benefits per type with overlapping dates, including:

Section 125 Vision
Section 125 Dental
Section 125 Medical
Section 125 Medical (other)
Section 125 Disability
Section 125 Accident
Section 125 Cancer
Section 125 Critical Illness
Section 125 Hospital
Section 125 Life

All other benefits, including 401k, HSA, Simple IRA, etc., are limited to one benefit effective at any time.

If a benefit is created that would put the employee over the type's limit of benefits with overlapping effective dates, the POST request will fail with a message:

Can only have a maximum of {limit} employee benefit of this type with overlapping effective dates

Creating Benefits

Create a "one-time" benefit

This example defines a one-time employee-only contribution of $125 to a section 125 Dental plan. Note that the effective start and effective end are the same day. In order for this Benefit to be applied to the employee, the employee must have a payroll item on a payroll with a payday of “2021-04-01”.

curl -X POST \
  https://sandbox.checkhq.com/benefits \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee":"emp_FZEOSqW0QTKcE1iVU1C5",
      "benefit": "125_dental",
      "company_contribution_amount": "0",
      "employee_contribution_amount": "125",
      "effective_start": "2021-04-01",
      "effective_end": "2021-04-01",
      "description": "Employee Dental Plan Contribution"
   }'

Example response

{
    "id": "ben_QI3vspnG34jAZcwnrFS5",
    "employee": "emp_FZEOSqW0QTKcE1iVU1C5",
    "benefit": "125_dental",
    "company_benefit": null,
    "description": "Employee Dental Plan Contribution",
    "effective_start": "2021-04-01",
    "effective_end": "2021-04-01",
    "company_contribution_amount": "0.00",
    "company_contribution_percent": null,
    "employee_contribution_amount": "125.00",
    "employee_contribution_percent": null,
    "hsa_contribution_limit": null
}

Create a recurring employee-only contribution

This example defines a recurring employee-only 401(k) contribution, for a set amount of $150 per pay period.

curl -X POST \
  https://sandbox.checkhq.com/benefits \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee":"emp_FZEOSqW0QTKcE1iVU1C5",
      "benefit": "401k",
      "company_contribution_amount": "0",
      "employee_contribution_amount": "150",
      "effective_start": "2021-04-01",
      "description": "Employee 401k plan"
   }'

Example response

{
    "id": "ben_QWLA9oP9WNVOUXYtBXvS",
    "employee": "emp_FZEOSqW0QTKcE1iVU1C5",
    "benefit": "401k",
    "company_benefit": null,
    "description": "Employee 401k plan",
    "effective_start": "2021-04-01",
    "effective_end": null,
    "company_contribution_amount": "0.00",
    "company_contribution_percent": null,
    "employee_contribution_amount": "150.00",
    "employee_contribution_percent": null,
    "hsa_contribution_limit": null
}

Create a shared recurring benefit

This example defines a recurring 125_medical Benefit, to which both the employer and the employee contribute. The employer contributes $275 per pay period, and the employee contributes $38.

curl -X POST \
  https://sandbox.checkhq.com/benefits \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee": "emp_bvNhcPxrbvRqgyCrlUcj",
      "benefit": "125_medical",
      "employee_contribution_amount": "38",
      "effective_start": "2021-04-01",
      "description": "Company sponsored medical insurance",
      "company_contribution_amount": "275"
   }'

Example response

{
    "id": "ben_gydbLvSlQiv0XYweHWeb",
    "employee": "emp_bvNhcPxrbvRqgyCrlUcj",
    "benefit": "125_medical",
    "company_benefit": null,
    "description": "Company sponsored medical insurance",
    "effective_start": "2021-04-01",
    "effective_end": null,
    "company_contribution_amount": "275.00",
    "company_contribution_percent": null,
    "employee_contribution_amount": "38.00",
    "employee_contribution_percent": null,
    "hsa_contribution_limit": null
}

Create a period benefit

This example creates a monthly period benefit for an employee, for which a $200 employee contribution will be distributed across all payrolls in a month. See the Period Benefits guide for more information.

curl -X POST \
  https://sandbox.checkhq.com/benefits \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee": "emp_bvNhcPxrbvRqgyCrlUcj",
      "benefit": "125_medical",
      "period": "monthly",
      "employee_period_amount": "200.00",
      "company_period_amount": null,
      "effective_start": "2021-04-01",
      "description": "Company sponsored medical insurance"
   }'

Example response

{
   "id": "ben_zp7zg2EcqRThtxoKXOjJ",
   "employee": "emp_bvNhcPxrbvRqgyCrlUcj",
   "benefit": "125_medical",
   "company_benefit": null,
   "description": "Company sponsored medical insurance",
   "period": "monthly",
   "effective_start": "2021-04-01",
   "effective_end": null,
   "company_contribution_amount": null,
   "company_contribution_percent": null,
   "company_period_amount": "0.00",
   "employee_contribution_amount": null,
   "employee_contribution_percent": null,
   "employee_period_amount": "200.00",
   "hsa_contribution_limit": null,
   "metadata": {}
}

Create an HSA benefit

This example defines an HSA Benefit with family coverage. Since the hsa_contribution_limit is passed as family, the maximum amount that will be contributed to this account will be the family limit for 2021, which is $7,200.

curl -X POST \
  https://sandbox.checkhq.com/benefits \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee": "emp_dF9KJgdpJMFGfXgTRctE",
      "benefit": "hsa",
      "company_contribution_amount": "0",
      "employee_contribution_amount": "375",
      "effective_start": "2021-04-01",
      "description": "HSA family",
      "effective_end": null,
      "hsa_contribution_limit": "family"
   }'

Example response

{
    "id": "ben_9xu6bkPKRRTqCj1IOdIZ",
    "employee": "emp_dF9KJgdpJMFGfXgTRctE",
    "benefit": "hsa",
    "company_benefit": null,
    "description": "HSA family",
    "effective_start": "2021-04-01",
    "effective_end": null,
    "company_contribution_amount": "0.00",
    "company_contribution_percent": null,
    "employee_contribution_amount": "375.00",
    "employee_contribution_percent": null,
    "hsa_contribution_limit": "family"
}

Create a company benefit

This example defines a 401k benefit at a company level with a default employee contribution amount and employer contribution percent.

curl -X POST \
  https://sandbox.checkhq.com/company_benefits \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "company":"com_FZEOSqW0QTKcE1iVU1C5",
      "benefit": "401k",
      "company_contribution_percent": 5.5,
      "employee_contribution_amount": "10",
      "effective_start": "2021-04-01",
      "description": "Riddler Car Repair 401k"
   }'

Example response

{
    "id": "cbn_QI3vspnG34jAZcwnrFS5",
    "company": "com_FZEOSqW0QTKcE1iVU1C5",
    "benefit": "401k",
    "description": "Riddler Car Repair 401k",
    "effective_start": "2021-04-01",
    "effective_end": null,
    "company_contribution_amount": null,
    "company_contribution_percent": 5.5,
    "employee_contribution_amount": "10.00",
    "employee_contribution_percent": null,
}

Create an employee benefit that inherits from a company benefit

This example defines an employee benefit that overrides the default employee contribution amount and effective start in the company benefit it inherits from.

curl -X POST \
  https://sandbox.checkhq.com/benefits \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee":"emp_FZEOSqW0QTKcE1iVU1C5",
      "company_benefit": "cbn_QI3vspnG34jAZcwnrFS5",
      "employee_contribution_amount": "5",
      "effective_start": "2021-05-01",
      "description": "Riddler Car Repair 401k"
   }'

Example response

{
    "id": "ben_QI3vs3213G34AZcwnrFS5",
    "employee": "emp_FZEOSqW0QTKcE1iVU1C5",
    "benefit": "401k",
    "company_benefit": "cbn_QI3vspnG34jAZcwnrFS5",
    "description": "Riddler Car Repair 401k",
    "effective_start": "2021-05-01",
    "effective_end": null,
    "company_contribution_amount": null,
    "company_contribution_percent": 5.5,
    "employee_contribution_amount": "5.00",
    "employee_contribution_percent": null,
}

Updating Benefits

All fields of a Benefit may be updated except for the employee field, company_benefit field, and the benefit field (which denotes the Benefit type). Changes will impact how the Benefit applies to future payrolls. Changes will not affect how the deduction has applied to previously paid or currently approved payrolls.

As an example, let’s say that an employee wishes to change their 401(k) contribution each payroll from a fixed amount of $100, to 12% of their income. That change could be facilitated by the following request, assuming the Benefit already existed with id “ben_QWLA9oP9WNVOUXYtBXvS”:

curl -X PATCH \
  https://sandbox.checkhq.com/benefits/ben_QWLA9oP9WNVOUXYtBXvS \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
      "employee_contribution_percent": 12.0,
   }'

Example response

{
    "id": "ben_QWLA9oP9WNVOUXYtBXvS",
    "employee": "emp_1ATPRmtf6XBdR6jDa9M5",
    "benefit": "401k",
    "description": "401k benefit",
    "effective_start": "2021-01-01",
    "effective_end": null,
    "company_contribution_amount": null,
    "company_contribution_percent": 10.0,
    "employee_contribution_amount": null,
    "employee_contribution_percent": 12.0,
    "hsa_contribution_limit": null
}

Deleting Benefits

Deleting a Benefit will remove it forever and prevent it from applying to any future payrolls. A deleted Benefit will not be returned by GET /benefits or GET /company_benefits calls. Calling GET /benefits/:id for a deleted Benefit will return a 404 error. Deleting a benefit will not impact previously paid or already approved payrolls nor will it impact existing reports and paystubs.

Delete a Benefit if it was created by mistake, or if it no longer applies to an employee. For example, a Benefit with an effective_end date that has passed.

curl -X DELETE \
  https://sandbox.checkhq.com/benefits/ben_0DeumV1lYhUua7xUWElX \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Note: The Check system saves a record of all Benefits for auditability.

Overriding Benefits for a single payroll

There are certain scenarios where the contribution amounts for a benefit need to be changed on a payroll while keeping future contributions the same. The benefit_override feature can be used to avoid having to update the benefit multiple times to achieve this functionality. Benefit overrides can be added to a payroll item on payroll creation and updates as well as payroll item updates.

This field should be passed to Check under a payroll item like this:

{
    "id": "itm_yvmmsVGFxLoBaMIkqzea",     
    "benefit_overrides": [
        {
            "benefit": "ben_SZhG3uagj9u8b3M6vFKt",
            "employee_contribution_amount": "400.00",
            "company_contribution_amount": null,
        }
    ],
}

Note: Overriding a benefit's contribution will still follow the benefits respective annual limit.